/ Hex Artifact Content
Login

Artifact 1754955ca803b9479a1c91bc130ed2b2a34881fd:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 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 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5630: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5640: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5650: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 61 70  * The xDeviceCap
5660: 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64  abilities method
5670: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
5680: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5690: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
56a0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
56b0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
56c0: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
56d0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
56e0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
56f0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5700: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5710: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5720: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5730: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5740: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5750: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
5760: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5770: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
5780: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
5790: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
57a0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
57b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57c0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
57d0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
57e0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
57f0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5800: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5810: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5820: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5830: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5840: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5850: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5860: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5870: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5880: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5890: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
58a0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
58b0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
58c0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
58d0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
58e0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
58f0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5900: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5910: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5920: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5930: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5940: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5950: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5960: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5970: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5980: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5990: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
59a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
59b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
59c0: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
59d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59e0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
59f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5a00: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5a10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
5a20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5a30: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5a40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5a50: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
5a60: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
5a70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5a80: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5a90: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5aa0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5ab0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ac0: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
5ad0: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
5ae0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5af0: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
5b00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5b10: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
5b20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5b30: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
5b40: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5b50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5b60: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
5b70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5b80: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5b90: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
5ba0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
5bb0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
5bc0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5bd0: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
5be0: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
5bf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c00: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
5c10: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
5c20: 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000800../*.** C
5c30: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
5c40: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
5c50: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
5c60: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
5c70: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5c80: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
5c90: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
5ca0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
5cb0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5cc0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
5cd0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
5ce0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5cf0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5d00: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
5d10: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
5d20: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
5d30: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
5d40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5d50: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
5d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d70: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
5d80: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
5d90: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
5da0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
5db0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
5dc0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
5dd0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
5de0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
5df0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
5e00: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
5e10: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
5e20: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
5e30: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
5e40: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
5e50: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
5e60: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
5e70: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
5e80: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
5e90: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
5ea0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
5eb0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
5ec0: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
5ed0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
5ee0: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
5ef0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
5f00: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
5f10: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
5f20: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
5f30: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
5f40: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
5f50: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
5f60: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
5f70: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
5f80: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
5f90: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
5fa0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
5fb0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
5fc0: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
5fd0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
5fe0: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
5ff0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65   fsync()..*/.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
6010: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
6020: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
6030: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6040: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
6050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6060: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
6070: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
6080: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
6090: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
60a0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
60b0: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
60c0: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
60d0: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
60e0: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
60f0: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
6100: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
6110: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
6120: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
6130: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
6140: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
6150: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
6160: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
6170: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
6180: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
6190: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
61a0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
61b0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
61c0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
61d0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
61e0: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
61f0: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
6200: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
6210: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
6220: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
6230: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
6240: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
6250: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
6260: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
6270: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
6280: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
6290: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
62a0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
62b0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
62c0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
62d0: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
62e0: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
62f0: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
6300: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
6310: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f  [sqlite3_vfs] xO
6320: 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  pen method popul
6330: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
6340: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
6350: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
6360: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
6370: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
6380: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
6390: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
63a0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
63b0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
63c0: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
63d0: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
63e0: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
63f0: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
6400: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
6410: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
6420: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
6430: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6440: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
6450: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
6460: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
6470: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
6480: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
6490: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
64a0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
64b0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
64c0: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
64d0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
64e0: 65 76 65 6e 20 69 66 20 74 68 65 20 78 4f 70 65  even if the xOpe
64f0: 6e 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  n reported that 
6500: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
6510: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
6520: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
6530: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
6540: 67 20 61 20 66 61 69 6c 65 64 20 78 4f 70 65 6e  g a failed xOpen
6550: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 78  .** is for the x
6560: 4f 70 65 6e 20 74 6f 20 73 65 74 20 74 68 65 20  Open to set the 
6570: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
6580: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f  thods element to
6590: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
65a0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
65b0: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
65c0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
65d0: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
65e0: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
65f0: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
6600: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
6610: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
6620: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
6630: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
6640: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
6650: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
6660: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
6670: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
6680: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
6690: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
66a0: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
66b0: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
66c0: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
66d0: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
66e0: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
66f0: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
6700: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
6710: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
6720: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6730: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
6740: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
6750: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
6760: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
6770: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
6780: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
6790: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
67a0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
67b0: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
67c0: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
67d0: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
67e0: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
67f0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6800: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
6810: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
6820: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
6830: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
6840: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
6850: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
6860: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
6870: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
6880: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
6890: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
68a0: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
68b0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
68c0: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
68d0: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
68e0: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
68f0: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
6900: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
6910: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
6920: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
6930: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
6940: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
6950: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
6960: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
6970: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
6980: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
6990: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
69a0: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
69b0: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
69c0: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
69d0: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
69e0: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
69f0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
6a00: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
6a10: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
6a20: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
6a30: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
6a40: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
6a50: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
6a60: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
6a70: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
6a80: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
6a90: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
6aa0: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
6ab0: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
6ac0: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
6ad0: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
6ae0: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
6af0: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
6b00: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
6b10: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
6b20: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
6b30: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
6b40: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
6b50: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
6b60: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
6b70: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
6b80: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
6b90: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
6ba0: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
6bb0: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  * A [SQLITE_FCNT
6bc0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69  L_LOCKSTATE | li
6bd0: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
6be0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
6bf0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
6c00: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
6c10: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
6c20: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
6c30: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
6c40: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
6c50: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
6c60: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a  oid conflicts..*
6c70: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
6c80: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
6c90: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
6ca0: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
6cb0: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
6cc0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
6cd0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
6ce0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
6cf0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
6d00: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
6d10: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
6d20: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
6d30: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
6d40: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6d50: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
6d60: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
6d70: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
6d80: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
6d90: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
6da0: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
6db0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6dc0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
6dd0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
6de0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6df0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
6e00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6e10: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
6e20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6e30: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
6e40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6e50: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
6e60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6e70: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
6e80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6e90: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
6ea0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
6eb0: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
6ec0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6ed0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
6ee0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6ef0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
6f00: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6f10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
6f20: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
6f30: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6f40: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6f50: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6f60: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6f70: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
6f80: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6f90: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
6fa0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
6fb0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
6fc0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
6fd0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
6fe0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
6ff0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
7000: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
7010: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
7020: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
7030: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
7040: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
7050: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
7060: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
7070: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
7080: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
7090: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
70a0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
70b0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
70c0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
70d0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
70e0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
70f0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7100: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
7110: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
7120: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
7130: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
7140: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
7150: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
7160: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52  e()..**.** If xR
7170: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51  ead() returns SQ
7180: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
7190: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c  _READ it must al
71a0: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68  so fill.** in th
71b0: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e  e unread portion
71c0: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  s of the buffer 
71d0: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56  with zeros.  A V
71e0: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73  FS that.** fails
71f0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
7200: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20  ort reads might 
7210: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48  seem to work.  H
7220: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75  owever,.** failu
7230: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  re to zero-fill 
7240: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c  short reads will
7250: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64   eventually lead
7260: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   to.** database 
7270: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74  corruption..*/.t
7280: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7290: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
72a0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
72b0: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
72c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b  te3_io_methods {
72d0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
72e0: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
72f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7300: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28  .  int (*xRead)(
7310: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76  sqlite3_file*, v
7320: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
7330: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
7340: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57  fst);.  int (*xW
7350: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  rite)(sqlite3_fi
7360: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  le*, const void*
7370: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
7380: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
7390: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63  ;.  int (*xTrunc
73a0: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ate)(sqlite3_fil
73b0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
73c0: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  4 size);.  int (
73d0: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
73e0: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73  file*, int flags
73f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7400: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
7410: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
7420: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e  64 *pSize);.  in
7430: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74  t (*xLock)(sqlit
7440: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
7450: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29    int (*xUnlock)
7460: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7470: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  int);.  int (*xC
7480: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7490: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
74a0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
74b0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e    int (*xFileCon
74c0: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69  trol)(sqlite3_fi
74d0: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  le*, int op, voi
74e0: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  d *pArg);.  int 
74f0: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73  (*xSectorSize)(s
7500: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7510: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68   int (*xDeviceCh
7520: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73  aracteristics)(s
7530: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7540: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
7550: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
7560: 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69  version 1 */.  i
7570: 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71  nt (*xShmMap)(sq
7580: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7590: 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20   iPg, int pgsz, 
75a0: 69 6e 74 2c 20 69 6e 74 2a 2c 20 76 6f 69 64 20  int, int*, void 
75b0: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
75c0: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
75d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
75e0: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
75f0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
7600: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
7610: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
7620: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
7630: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
7640: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
7650: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
7660: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
7670: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
7680: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
7690: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
76a0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
76b0: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
76c0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
76d0: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
76e0: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
76f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
7700: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61  eger constants a
7710: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74  re opcodes for t
7720: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
7730: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
7740: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7750: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64  hods] object and
7760: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
7770: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
7780: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
7790: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
77a0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
77b0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
77c0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
77d0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
77e0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
77f0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
7800: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
7810: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
7820: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
7830: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
7840: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
7850: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
7860: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
7870: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
7880: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
7890: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
78a0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
78b0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
78c0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
78d0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
78e0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
78f0: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
7900: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c   testing and onl
7910: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
7920: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
7930: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64  ITE_TEST.** is d
7940: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
7950: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7960: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
7970: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
7980: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
7990: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
79a0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
79b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
79c0: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
79d0: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
79e0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
79f0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
7a00: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
7a10: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
7a20: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
7a30: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
7a40: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
7a50: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
7a60: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
7a70: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
7a80: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
7a90: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
7aa0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
7ab0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
7ac0: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
7ad0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
7ae0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
7af0: 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65  ATE        1.#de
7b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
7b10: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
7b20: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
7b30: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
7b40: 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65  YFILE      3.#de
7b50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
7b60: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
7b70: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
7b80: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
7b90: 49 4e 54 20 20 20 20 20 20 20 20 35 0a 0a 2f 2a  INT        5../*
7ba0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
7bb0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
7bc0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
7bd0: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
7be0: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
7bf0: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
7c00: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
7c10: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
7c20: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
7c30: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
7c40: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
7c50: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
7c60: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
7c70: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
7c80: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
7c90: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
7ca0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
7cb0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
7cc0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
7cd0: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
7ce0: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
7cf0: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
7d00: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
7d10: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
7d20: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
7d30: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7d40: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
7d50: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
7d60: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
7d70: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
7d80: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
7d90: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20  n.** the SQLite 
7da0: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
7db0: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
7dc0: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
7dd0: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
7de0: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
7df0: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
7e00: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
7e10: 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  m"..**.** The va
7e20: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
7e30: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
7e40: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
7e50: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
7e60: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
7e70: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
7e80: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
7e90: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
7ea0: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
7eb0: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
7ec0: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
7ed0: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
7ee0: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
7ef0: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
7f00: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
7f10: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
7f20: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
7f30: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
7f40: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
7f50: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
7f60: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
7f70: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
7f80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
7f90: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
7fa0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
7fb0: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
7fc0: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
7fd0: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
7fe0: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
7ff0: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
8000: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
8010: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
8020: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
8030: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
8040: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
8050: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
8060: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
8070: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
8080: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
8090: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
80a0: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
80b0: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
80c0: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
80d0: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
80e0: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
80f0: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
8100: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
8110: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
8120: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
8130: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
8140: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
8150: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
8160: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
8170: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
8180: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
8190: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
81a0: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
81b0: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
81c0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
81d0: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
81e0: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
81f0: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
8200: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
8210: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
8220: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
8230: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
8240: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
8250: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
8260: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
8270: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
8280: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
8290: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
82a0: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
82b0: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
82c0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
82d0: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
82e0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
82f0: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
8300: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
8310: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
8320: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
8330: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
8340: 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ll guarantee tha
8350: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
8360: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
8370: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
8380: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
8390: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
83a0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
83b0: 61 74 68 6e 61 6d 65 28 29 2e 20 20 53 51 4c 69  athname().  SQLi
83c0: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
83d0: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
83e0: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
83f0: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
8400: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
8410: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
8420: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
8430: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
8440: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
8450: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
8460: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
8470: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
8480: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
8490: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
84a0: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
84b0: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
84c0: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
84d0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 78  e parameter is x
84e0: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
84f0: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
8500: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
8510: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
8520: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
8530: 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20  file.  Whenever 
8540: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
8550: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
8560: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
8570: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
8580: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
8590: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
85a0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
85b0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
85c0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
85d0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
85e0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
85f0: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
8600: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
8610: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
8620: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
8630: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
8640: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
8650: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
8660: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
8670: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
8680: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
8690: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
86a0: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
86b0: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
86c0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
86d0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
86e0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
86f0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
8700: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
8710: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
8720: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
8730: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
8740: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
8750: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
8760: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
8770: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
8780: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
8790: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
87a0: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
87b0: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
87c0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
87d0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
87e0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
87f0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
8800: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
8810: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
8820: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
8830: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
8840: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
8850: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
8860: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
8870: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8880: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
8890: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
88a0: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
88b0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  L].** </ul>.**.*
88c0: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
88d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
88e0: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
88f0: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
8900: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
8910: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
8920: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
8930: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
8940: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
8950: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
8960: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
8970: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
8980: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
8990: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
89a0: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
89b0: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
89c0: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
89d0: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
89e0: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
89f0: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
8a00: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
8a10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
8a20: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
8a30: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
8a40: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
8a50: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
8a60: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
8a70: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
8a80: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
8a90: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
8aa0: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
8ab0: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
8ac0: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
8ad0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
8ae0: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
8af0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
8b00: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
8b10: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
8b20: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8b30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8b40: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
8b50: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
8b60: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
8b70: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
8b80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
8b90: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
8ba0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
8bb0: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
8bc0: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
8bd0: 6f 73 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  osed.  The [SQLI
8be0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8bf0: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
8c00: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20  e set for TEMP  
8c10: 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e  databases, journ
8c20: 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a  als and for subj
8c30: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54  ournals..**.** T
8c40: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
8c50: 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
8c60: 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69  is always used i
8c70: 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a  n conjunction.**
8c80: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
8c90: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66  E_OPEN_CREATE] f
8ca0: 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62  lag, which are b
8cb0: 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  oth directly.** 
8cc0: 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65  analogous to the
8cd0: 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52   O_EXCL and O_CR
8ce0: 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65  EAT flags of the
8cf0: 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a   POSIX open().**
8d00: 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54   API.  The SQLIT
8d10: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
8d20: 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72   flag, when pair
8d30: 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
8d40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
8d50: 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69  TE, is used to i
8d60: 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c  ndicate that fil
8d70: 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a  e should always.
8d80: 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61  ** be created, a
8d90: 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e  nd that it is an
8da0: 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72   error if it alr
8db0: 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20  eady exists..** 
8dc0: 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e  It is <i>not</i>
8dd0: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
8de0: 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  e the file shoul
8df0: 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20  d be opened .** 
8e00: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
8e10: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c  cess..**.** At l
8e20: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
8e30: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
8e40: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
8e50: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
8e60: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
8e70: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
8e80: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
8e90: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
8ea0: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
8eb0: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
8ec0: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
8ed0: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
8ee0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
8ef0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
8f00: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
8f10: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
8f20: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
8f30: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
8f40: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
8f50: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
8f60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
8f70: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
8f80: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
8f90: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
8fa0: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
8fb0: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
8fc0: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
8fd0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
8fe0: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
8ff0: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
9000: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
9010: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
9020: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
9030: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
9040: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   call..**.** The
9050: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
9060: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
9070: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
9080: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
9090: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
90a0: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
90b0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
90c0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
90d0: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
90e0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
90f0: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
9100: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
9110: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
9120: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
9130: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
9140: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
9150: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
9160: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
9170: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
9180: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
9190: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
91a0: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
91b0: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
91c0: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
91d0: 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73  me.  The exact s
91e0: 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
91f0: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61  t buffer.** is a
9200: 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20  lso passed as a 
9210: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74  parameter to bot
9220: 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  h  methods. If t
9230: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
9240: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
9250: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
9260: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
9270: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
9280: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
9290: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
92a0: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
92b0: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
92c0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
92d0: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
92e0: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
92f0: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
9300: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
9310: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
9320: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
9330: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
9340: 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  ), xCurrentTime(
9350: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
9360: 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e  imeInt64().** in
9370: 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74  terfaces are not
9380: 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74   strictly a part
9390: 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74   of the filesyst
93a0: 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65  em, but they are
93b0: 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  .** included in 
93c0: 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72  the VFS structur
93d0: 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65  e for completene
93e0: 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  ss..** The xRand
93f0: 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f  omness() functio
9400: 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  n attempts to re
9410: 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65  turn nBytes byte
9420: 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61  s.** of good-qua
9430: 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20  lity randomness 
9440: 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20  into zOut.  The 
9450: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a  return value is.
9460: 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75  ** the actual nu
9470: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
9480: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
9490: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c  ined..** The xSl
94a0: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
94b0: 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ses the calling 
94c0: 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20  thread to sleep 
94d0: 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20  for at.** least 
94e0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
94f0: 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e  croseconds given
9500: 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54  .  The xCurrentT
9510: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
9520: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
9530: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
9540: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
9550: 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20   and time as.** 
9560: 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
9570: 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 78   value..** The x
9580: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
9590: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
95a0: 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72  s, as an integer
95b0: 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20  , the Julian.** 
95c0: 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69  Day Number multi
95d0: 70 6c 65 64 20 62 79 20 38 36 34 30 30 30 30 30  pled by 86400000
95e0: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
95f0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
9600: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
9610: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
9620: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
9630: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
9640: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
9650: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
9660: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
9670: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
9680: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
9690: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
96a0: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
96b0: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
96c0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
96d0: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
96e0: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
96f0: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
9700: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
9710: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
9720: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
9730: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
9740: 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74  ite3_vfs;.struct
9750: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
9760: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
9770: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
9780: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
9790: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
97a0: 20 32 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   2) */.  int szO
97b0: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
97c0: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
97d0: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
97e0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
97f0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
9800: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
9810: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
9820: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
9830: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
9840: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
9850: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
9860: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
9870: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
9880: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
9890: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
98a0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
98b0: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
98c0: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
98d0: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
98e0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
98f0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9900: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
9910: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
9920: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
9930: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
9940: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
9950: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
9960: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
9970: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
9980: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
9990: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
99a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
99b0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
99c0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
99d0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
99e0: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
99f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
9a00: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
9a10: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
9a20: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
9a30: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
9a40: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
9a50: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
9a60: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
9a70: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
9a80: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
9a90: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
9aa0: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
9ab0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
9ac0: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
9ad0: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
9ae0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
9af0: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
9b00: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
9b10: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
9b20: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
9b30: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
9b40: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
9b50: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
9b60: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
9b70: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
9b80: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
9b90: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
9ba0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
9bb0: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
9bc0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
9bd0: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
9be0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
9bf0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
9c00: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
9c10: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
9c20: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
9c30: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
9c40: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
9c50: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
9c60: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
9c70: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
9c80: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
9c90: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
9ca0: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
9cb0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9cc0: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
9cd0: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
9ce0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
9cf0: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
9d00: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
9d10: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
9d20: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
9d30: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
9d40: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
9d50: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
9d60: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
9d70: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
9d80: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
9d90: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
9da0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
9db0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
9dc0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
9dd0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
9de0: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
9df0: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
9e00: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
9e10: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
9e20: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
9e30: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
9e40: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
9e50: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
9e60: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
9e70: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
9e80: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
9e90: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
9ea0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
9eb0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
9ec0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
9ed0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
9ee0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
9ef0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
9f00: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f  r the file is bo
9f10: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
9f20: 77 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74  writable..** Wit
9f30: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
9f40: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
9f50: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
9f60: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
9f70: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
9f80: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
9f90: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
9fa0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
9fb0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
9fc0: 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20  WRITE 1.#define 
9fd0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
9fe0: 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a  AD      2../*.**
9ff0: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
a000: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
a010: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
a020: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
a030: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
a040: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
a050: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
a060: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
a070: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
a080: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
a090: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
a0a0: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
a0b0: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
a0c0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
a0d0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
a0e0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
a0f0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
a100: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
a110: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
a120: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
a130: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
a140: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
a150: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
a160: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
a170: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
a180: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
a190: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
a1a0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
a1b0: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
a1c0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
a1d0: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
a1e0: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
a1f0: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
a200: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
a210: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20  ** was given no 
a220: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
a230: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
a240: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
a250: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
a260: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
a270: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
a280: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
a290: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
a2a0: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
a2b0: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
a2c0: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
a2d0: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
a2e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
a2f0: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
a300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a310: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
a320: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
a330: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
a340: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
a350: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
a360: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
a370: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
a380: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
a390: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
a3a0: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
a3b0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
a3c0: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
a3d0: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
a3e0: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
a3f0: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
a400: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
a410: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
a420: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
a430: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
a440: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
a450: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
a460: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
a470: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
a480: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
a490: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
a4a0: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
a4b0: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
a4c0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
a4d0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
a4e0: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
a4f0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
a500: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
a510: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
a520: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
a530: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
a540: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
a550: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
a560: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a570: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
a580: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
a590: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
a5a0: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
a5b0: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
a5c0: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
a5d0: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
a5e0: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
a5f0: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
a600: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
a610: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
a620: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
a630: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
a640: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
a650: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
a660: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
a670: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
a680: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
a690: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
a6a0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
a6b0: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
a6c0: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
a6d0: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
a6e0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
a6f0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
a700: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
a710: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
a720: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
a730: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
a740: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
a750: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
a760: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a770: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
a780: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
a790: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
a7a0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
a7b0: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
a7c0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
a7d0: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
a7e0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
a7f0: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
a800: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
a810: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a820: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
a830: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
a840: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
a850: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
a860: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
a870: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
a880: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
a890: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
a8a0: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
a8b0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
a8c0: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
a8d0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
a8e0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
a8f0: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
a900: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
a910: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
a920: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
a930: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
a940: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
a950: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
a960: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
a970: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
a980: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
a990: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a9a0: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
a9b0: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
a9c0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
a9d0: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
a9e0: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
a9f0: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
aa00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
aa10: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
aa20: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
aa30: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
aa40: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
aa50: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
aa60: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
aa70: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
aa80: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
aa90: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
aaa0: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
aab0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
aac0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
aad0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
aae0: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
aaf0: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
ab00: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
ab10: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
ab20: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
ab30: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
ab40: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
ab50: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
ab60: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
ab70: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
ab80: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
ab90: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
aba0: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
abb0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
abc0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
abd0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
abe0: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
abf0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
ac00: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
ac10: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
ac20: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
ac30: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
ac40: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
ac50: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
ac60: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
ac70: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
ac80: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
ac90: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
aca0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
acb0: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
acc0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
acd0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
ace0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
acf0: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
ad00: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
ad10: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
ad20: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
ad30: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
ad40: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
ad50: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
ad60: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
ad70: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
ad80: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
ad90: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
ada0: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
adb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
adc0: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
add0: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
ade0: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
adf0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ae00: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
ae10: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
ae20: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
ae30: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
ae40: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
ae50: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
ae60: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
ae70: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
ae80: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
ae90: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
aea0: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
aeb0: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
aec0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
aed0: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
aee0: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
aef0: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
af00: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
af10: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
af20: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
af30: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
af40: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
af50: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
af60: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
af70: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
af80: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
af90: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
afa0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
afb0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
afc0: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
afd0: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
afe0: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
aff0: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
b000: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
b010: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
b020: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
b030: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
b040: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
b050: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
b060: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
b070: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
b080: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
b090: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
b0a0: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
b0b0: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
b0c0: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
b0d0: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
b0e0: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
b0f0: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
b100: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
b110: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
b120: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
b130: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
b140: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
b150: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
b160: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
b170: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
b180: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
b190: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
b1a0: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
b1b0: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
b1c0: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
b1d0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
b1e0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
b1f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
b200: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
b210: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
b220: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
b230: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
b240: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
b250: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
b260: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
b270: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
b280: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
b290: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
b2a0: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
b2b0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
b2c0: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
b2d0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
b2e0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
b2f0: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
b300: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
b310: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
b320: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
b330: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
b340: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
b350: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
b360: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
b370: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
b380: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
b390: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
b3a0: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
b3b0: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
b3c0: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
b3d0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
b3e0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
b3f0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
b400: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
b410: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
b420: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
b430: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
b440: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
b450: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
b460: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
b470: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
b480: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
b490: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
b4a0: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
b4b0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
b4c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
b4d0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
b4e0: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
b4f0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
b500: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
b510: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
b520: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
b530: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
b540: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
b550: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
b560: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
b570: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
b580: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
b590: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
b5a0: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
b5b0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
b5c0: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
b5d0: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
b5e0: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
b5f0: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
b600: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
b610: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
b620: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
b630: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
b640: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
b650: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
b660: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
b670: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
b680: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
b690: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
b6a0: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
b6b0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
b6c0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
b6d0: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
b6e0: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
b6f0: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
b700: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
b710: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
b720: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
b730: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
b740: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
b750: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
b760: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
b770: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
b780: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
b790: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
b7a0: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
b7b0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
b7c0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
b7d0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
b7e0: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
b7f0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
b800: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
b810: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b820: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
b830: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
b840: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
b850: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
b860: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
b870: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
b880: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
b890: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
b8a0: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
b8b0: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
b8c0: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
b8d0: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
b8e0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
b8f0: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
b900: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
b910: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
b920: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
b930: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
b940: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
b950: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
b960: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c  G_SINGLETHREAD |
b970: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
b980: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
b990: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
b9a0: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
b9b0: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
b9c0: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
b9d0: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
b9e0: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
b9f0: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  n the [SQLITE_CO
ba00: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
ba10: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  D | configuratio
ba20: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
ba30: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
ba40: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
ba50: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
ba60: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
ba70: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ba80: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
ba90: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
baa0: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
bab0: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
bac0: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
bad0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
bae0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
baf0: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
bb00: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
bb10: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
bb20: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
bb30: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
bb40: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
bb50: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
bb60: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
bb70: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
bb80: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
bb90: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
bba0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
bbb0: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
bbc0: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
bbd0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
bbe0: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
bbf0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
bc00: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
bc10: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
bc20: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
bc30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bc40: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
bc50: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
bc60: 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  nt).  The.** sql
bc70: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
bc80: 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c   interface shoul
bc90: 64 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69  d only be used i
bca0: 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
bcb0: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
bcc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
bcd0: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
bce0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a  lite3_open()],.*
bcf0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
bd00: 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  6()], or [sqlite
bd10: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a  3_open_v2()].  .
bd20: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
bd30: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
bd40: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
bd50: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
bd60: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
bd70: 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67   verb - an integ
bd80: 65 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64  er code that ind
bd90: 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61  icates what.** a
bda0: 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
bdb0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
bdc0: 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
bdd0: 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f  igured..** The o
bde0: 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74  nly choice for t
bdf0: 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51  his value is [SQ
be00: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
be10: 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77  OKASIDE]..** New
be20: 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c   verbs are likel
be30: 79 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e  y to be added in
be40: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
be50: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41   of SQLite..** A
be60: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
be70: 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68  nts depend on th
be80: 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  e verb..**.** ^C
be90: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
bea0: 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
beb0: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
bec0: 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
bed0: 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
bee0: 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
bef0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
bf00: 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
bf10: 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
bf20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
bf30: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
bf40: 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
bf50: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
bf60: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
bf70: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
bf80: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
bf90: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
bfa0: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
bfb0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
bfc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
bfd0: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
bfe0: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
bff0: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
c000: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
c010: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
c020: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
c030: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
c040: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
c050: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
c060: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
c070: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
c080: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
c090: 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
c0a0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
c0b0: 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
c0c0: 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
c0d0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
c0e0: 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
c0f0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
c100: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
c110: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
c120: 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
c130: 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
c140: 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
c150: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
c160: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
c170: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
c180: 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
c190: 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
c1a0: 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
c1b0: 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
c1c0: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
c1d0: 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
c1e0: 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
c1f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
c200: 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
c210: 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
c220: 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
c230: 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
c240: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
c250: 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
c260: 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
c270: 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
c280: 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
c290: 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
c2a0: 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
c2b0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
c2c0: 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
c2d0: 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
c2e0: 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
c2f0: 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
c300: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
c310: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
c320: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
c330: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
c340: 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
c350: 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
c360: 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
c370: 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
c380: 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
c390: 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
c3a0: 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
c3b0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
c3c0: 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72   xMalloc and xFr
c3d0: 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
c3e0: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
c3f0: 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
c400: 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
c410: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
c420: 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54   C library..** T
c430: 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68  he xRealloc meth
c440: 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  od must work lik
c450: 65 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d  e realloc() from
c460: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
c470: 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68 20  library.** with 
c480: 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 68  the exception th
c490: 61 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e 64  at if the second
c4a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52 65   argument to xRe
c4b0: 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a  alloc is zero,.*
c4c0: 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20  * xRealloc must 
c4d0: 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20  be a no-op - it 
c4e0: 6d 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d  must not perform
c4f0: 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20   any allocation 
c500: 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69  or.** deallocati
c510: 6f 6e 2e 20 20 5e 53 51 4c 69 74 65 20 67 75 61  on.  ^SQLite gua
c520: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
c530: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
c540: 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
c550: 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
c560: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
c570: 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
c580: 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73  oundup..** And s
c590: 6f 20 69 6e 20 63 61 73 65 73 20 77 68 65 72 65  o in cases where
c5a0: 20 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79 73   xRoundup always
c5b0: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74   returns a posit
c5c0: 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78  ive number,.** x
c5d0: 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66  Realloc can perf
c5e0: 6f 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20 74  orm exactly as t
c5f0: 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72  he standard libr
c600: 61 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  ary realloc() an
c610: 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e  d.** still be in
c620: 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74 68   compliance with
c630: 20 74 68 69 73 20 73 70 65 63 69 66 69 63 61 74   this specificat
c640: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  ion..**.** xSize
c650: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
c660: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
c670: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
c680: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
c690: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
c6a0: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
c6b0: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
c6c0: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
c6d0: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
c6e0: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
c6f0: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
c700: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
c710: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
c720: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
c730: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
c740: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
c750: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
c760: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c770: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
c780: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
c790: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
c7a0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
c7b0: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
c7c0: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
c7d0: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
c7e0: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
c7f0: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
c800: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
c810: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
c820: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
c830: 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
c840: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c850: 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
c860: 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
c870: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
c880: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
c890: 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
c8a0: 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
c8b0: 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
c8c0: 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
c8d0: 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
c8e0: 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
c8f0: 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
c900: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
c910: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
c920: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
c930: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
c940: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
c950: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
c960: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
c970: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
c980: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
c990: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
c9a0: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
c9b0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
c9c0: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
c9d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
c9e0: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
c9f0: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
ca00: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
ca10: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
ca20: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
ca30: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
ca40: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
ca50: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
ca60: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
ca70: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
ca80: 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
ca90: 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
caa0: 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
cab0: 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
cac0: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
cad0: 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
cae0: 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
caf0: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
cb00: 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
cb10: 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
cb20: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
cb30: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
cb40: 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
cb50: 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
cb60: 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
cb70: 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
cb80: 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
cb90: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
cba0: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
cbb0: 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
cbc0: 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
cbd0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
cbe0: 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
cbf0: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
cc00: 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
cc10: 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
cc20: 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
cc30: 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
cc40: 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
cc50: 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
cc60: 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
cc70: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
cc80: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
cc90: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
cca0: 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
ccb0: 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
ccc0: 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
ccd0: 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
cce0: 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
ccf0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
cd00: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
cd10: 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
cd20: 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
cd30: 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
cd40: 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
cd50: 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
cd60: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
cd70: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
cd80: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
cd90: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
cda0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
cdb0: 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
cdc0: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
cdd0: 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
cde0: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
cdf0: 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
ce00: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
ce10: 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
ce20: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
ce30: 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
ce40: 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
ce50: 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
ce60: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
ce70: 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
ce80: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
ce90: 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
cea0: 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
ceb0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
cec0: 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
ced0: 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
cee0: 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
cef0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
cf00: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
cf10: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
cf20: 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
cf30: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
cf40: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
cf50: 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
cf60: 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
cf70: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
cf80: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
cf90: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
cfa0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
cfb0: 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
cfc0: 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
cfd0: 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
cfe0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
cff0: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
d000: 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
d010: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
d020: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
d030: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
d040: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
d050: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
d060: 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
d070: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
d080: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
d090: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
d0a0: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
d0b0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
d0c0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
d0d0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
d0e0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
d0f0: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
d100: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
d110: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
d120: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
d130: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
d140: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
d150: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
d160: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
d170: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
d180: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
d190: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
d1a0: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
d1b0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
d1c0: 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
d1d0: 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
d1e0: 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
d1f0: 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
d200: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
d210: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
d220: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
d230: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
d240: 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
d250: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
d260: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
d270: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
d280: 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
d290: 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
d2a0: 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
d2b0: 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
d2c0: 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
d2d0: 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
d2e0: 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
d2f0: 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
d300: 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
d310: 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
d320: 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
d330: 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
d340: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
d350: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
d360: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
d370: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
d380: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
d390: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
d3a0: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
d3b0: 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
d3c0: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
d3d0: 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
d3e0: 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
d3f0: 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
d400: 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
d410: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
d420: 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
d430: 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
d440: 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
d450: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
d460: 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
d470: 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
d480: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
d490: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
d4a0: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
d4b0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
d4c0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
d4d0: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
d4e0: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
d4f0: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
d500: 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
d510: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
d520: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
d530: 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
d540: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d550: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
d560: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
d570: 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
d580: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
d590: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
d5a0: 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
d5b0: 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
d5c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
d5d0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
d5e0: 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
d5f0: 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
d600: 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
d610: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
d620: 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
d630: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
d640: 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
d650: 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
d660: 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
d670: 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
d680: 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
d690: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
d6a0: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
d6b0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
d6c0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
d6d0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
d6e0: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
d6f0: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
d700: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
d710: 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
d720: 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
d730: 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
d740: 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
d750: 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
d760: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
d770: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
d780: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
d790: 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
d7a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
d7b0: 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
d7c0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
d7d0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
d7e0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
d7f0: 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
d800: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
d810: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
d820: 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
d830: 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
d840: 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
d850: 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
d860: 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
d870: 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
d880: 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
d890: 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
d8a0: 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
d8b0: 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
d8c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d8d0: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
d8e0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
d8f0: 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
d900: 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
d910: 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
d920: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
d930: 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
d940: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
d950: 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
d960: 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
d970: 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
d980: 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
d990: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
d9a0: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
d9b0: 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
d9c0: 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
d9d0: 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
d9e0: 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
d9f0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
da00: 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
da10: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
da20: 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
da30: 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
da40: 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
da50: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
da60: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
da70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
da80: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
da90: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
daa0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
dab0: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
dac0: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
dad0: 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
dae0: 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
daf0: 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
db00: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
db10: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
db20: 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
db30: 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
db40: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
db50: 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
db60: 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
db70: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
db80: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
db90: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
dba0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
dbb0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
dbc0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
dbd0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
dbe0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
dbf0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
dc00: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
dc10: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
dc20: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
dc30: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
dc40: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
dc50: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
dc60: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
dc70: 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
dc80: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
dc90: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
dca0: 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
dcb0: 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
dcc0: 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
dcd0: 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
dce0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
dcf0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
dd00: 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
dd10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
dd20: 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
dd30: 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
dd40: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
dd50: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
dd60: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
dd70: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
dd80: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
dd90: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
dda0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
ddb0: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
ddc0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
ddd0: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
dde0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
ddf0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
de00: 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
de10: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
de20: 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
de30: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
de40: 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
de50: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
de60: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
de70: 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
de80: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
de90: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
dea0: 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
deb0: 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
dec0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
ded0: 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
dee0: 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
def0: 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
df00: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
df10: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
df20: 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
df30: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
df40: 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
df50: 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20  nt of type int, 
df60: 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
df70: 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68   .** boolean, wh
df80: 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
df90: 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
dfa0: 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79  ection of memory
dfb0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20   allocation .** 
dfc0: 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
dfd0: 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
dfe0: 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
dff0: 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68  are disabled, th
e000: 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  e .** following 
e010: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
e020: 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
e030: 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
e040: 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
e050: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
e060: 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
e070: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
e080: 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
e090: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
e0a0: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
e0b0: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
e0c0: 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
e0d0: 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
e0e0: 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
e0f0: 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
e100: 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
e110: 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
e120: 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
e130: 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
e140: 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
e150: 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
e160: 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
e170: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
e180: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
e190: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
e1a0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
e1b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
e1c0: 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
e1d0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
e1e0: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
e1f0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
e200: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
e210: 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63  se for.** scratc
e220: 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65  h memory.  There
e230: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
e240: 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72  ents:  A pointer
e250: 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
e260: 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
e270: 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
e280: 68 65 20 73 63 72 61 63 68 20 61 6c 6c 6f 63 61  he scrach alloca
e290: 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
e2a0: 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
e2b0: 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
e2c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
e2d0: 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
e2e0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
e2f0: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
e300: 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
e310: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
e320: 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
e330: 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72  f 16. The sz par
e340: 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
e350: 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20   a few bytes.** 
e360: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
e370: 61 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73  actual scratch s
e380: 70 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75  pace required du
e390: 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 6f 76  e to internal ov
e3a0: 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66  erhead..** The f
e3b0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
e3c0: 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
e3d0: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
e3e0: 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
e3f0: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
e400: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
e410: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
e420: 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
e430: 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75  n one scratch bu
e440: 66 66 65 72 20 70 65 72 20 74 68 72 65 61 64 2e  ffer per thread.
e450: 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64    So.** N should
e460: 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 65   be set to the e
e470: 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
e480: 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
e490: 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
e4a0: 0a 2a 2a 20 6e 65 76 65 72 20 72 65 71 75 69 72  .** never requir
e4b0: 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  e a scratch buff
e4c0: 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
e4d0: 74 68 61 6e 20 36 20 74 69 6d 65 73 20 74 68 65  than 6 times the
e4e0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67   database.** pag
e4f0: 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69  e size. ^If SQLi
e500: 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
e510: 64 64 69 74 69 6f 6e 61 6c 20 73 63 72 61 74 63  dditional scratc
e520: 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
e530: 0a 2a 2a 20 77 68 61 74 20 69 73 20 70 72 6f 76  .** what is prov
e540: 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e  ided by this con
e550: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e560: 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c  n, then .** [sql
e570: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77  ite3_malloc()] w
e580: 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f  ill be used to o
e590: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
e5a0: 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a   needed.</dd>.**
e5b0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
e5c0: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
e5d0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
e5e0: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
e5f0: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
e600: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
e610: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
e620: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
e630: 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
e640: 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
e650: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
e660: 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  enation.  .** Th
e670: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
e680: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
e690: 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
e6a0: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
e6b0: 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
e6c0: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
e6d0: 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
e6e0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
e6f0: 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  HE option..** Th
e700: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
e710: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
e720: 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
e730: 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
e740: 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
e750: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
e760: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
e770: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
e780: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
e790: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
e7a0: 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
e7b0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
e7c0: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
e7d0: 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
e7e0: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
e7f0: 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
e800: 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
e810: 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
e820: 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
e830: 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
e840: 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
e850: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
e860: 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
e870: 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
e880: 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
e890: 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
e8a0: 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
e8b0: 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
e8c0: 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
e8d0: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
e8e0: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
e8f0: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
e900: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
e910: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
e920: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
e930: 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
e940: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
e950: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
e960: 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
e970: 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
e980: 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
e990: 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
e9a0: 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
e9b0: 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
e9c0: 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
e9d0: 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
e9e0: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
e9f0: 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
ea00: 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
ea10: 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
ea20: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
ea30: 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
ea40: 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
ea50: 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  * ^The implement
ea60: 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65 20  ation might use 
ea70: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
ea80: 68 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f 20  he N buffers to 
ea90: 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20  hold .** memory 
eaa0: 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72  accounting infor
eab0: 6d 61 74 69 6f 6e 2e 20 54 68 65 20 70 6f 69 6e  mation. The poin
eac0: 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
ead0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
eae0: 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
eaf0: 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
eb00: 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
eb10: 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
eb20: 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
eb30: 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
eb40: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
eb50: 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
eb60: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
eb70: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
eb80: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
eb90: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
eba0: 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66  te will use.** f
ebb0: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
ebc0: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
ebd0: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65  ocation needs be
ebe0: 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
ebf0: 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53  ded.** for by [S
ec00: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
ec10: 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATCH] and [SQLIT
ec20: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
ec30: 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  HE]..** There ar
ec40: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
ec50: 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  s: An 8-byte ali
ec60: 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
ec70: 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
ec80: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
ec90: 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
eca0: 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
ecb0: 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
ecc0: 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  ion size..** ^If
ecd0: 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
ece0: 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
ecf0: 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
ed00: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
ed10: 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
ed20: 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
ed30: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
ed40: 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
ed50: 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
ed60: 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
ed70: 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
ed80: 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
ed90: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
eda0: 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72  ^If the.** memor
edb0: 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
edc0: 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72   NULL and either
edd0: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
ede0: 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b  MEMSYS3] or.** [
edf0: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
ee00: 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e  MSYS5] are defin
ee10: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ed, then the alt
ee20: 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
ee30: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
ee40: 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
ee50: 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
ee60: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ee70: 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
ee80: 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
ee90: 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
eea0: 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
eeb0: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
eec0: 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
eed0: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
eee0: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
eef0: 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
ef00: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
ef10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
ef20: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
ef30: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
ef40: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
ef50: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
ef60: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
ef70: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
ef80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
ef90: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
efa0: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
efb0: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
efc0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
efd0: 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
efe0: 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
eff0: 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
f000: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
f010: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
f020: 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
f030: 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
f040: 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20  e.** content of 
f050: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
f060: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
f070: 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
f080: 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
f090: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
f0a0: 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
f0b0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
f0c0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
f0d0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
f0e0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
f0f0: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
f100: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
f110: 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
f120: 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
f130: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
f140: 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
f150: 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
f160: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f170: 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
f180: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
f190: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
f1a0: 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
f1b0: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
f1c0: 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ].</dd>.**.** <d
f1d0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
f1e0: 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
f1f0: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
f200: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
f210: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
f220: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
f230: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
f240: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
f250: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
f260: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
f270: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
f280: 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
f290: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
f2a0: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
f2b0: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
f2c0: 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
f2d0: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
f2e0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
f2f0: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
f300: 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
f310: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
f320: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
f330: 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
f340: 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
f350: 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
f360: 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
f370: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
f380: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
f390: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
f3a0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
f3b0: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
f3c0: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
f3d0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
f3e0: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
f3f0: 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
f400: 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
f410: 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
f420: 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
f430: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
f440: 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
f450: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
f460: 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
f470: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
f480: 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
f490: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
f4a0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
f4b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
f4c0: 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
f4d0: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
f4e0: 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
f4f0: 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
f500: 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  ne the default.*
f510: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
f520: 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b  ion for the look
f530: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
f540: 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a  ocator on each.*
f550: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
f560: 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69  ection].  The fi
f570: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
f580: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
f590: 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
f5a0: 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
f5b0: 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
f5c0: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
f5d0: 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
f5e0: 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
f5f0: 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54  nnection.)^  ^(T
f600: 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
f610: 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c  the.** <i>defaul
f620: 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
f630: 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
f640: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
f650: 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f  SIDE].** verb to
f660: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
f670: 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
f680: 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
f690: 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
f6a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
f6b0: 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
f6c0: 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
f6d0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
f6e0: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f 64  CONFIG_PCACHE</d
f6f0: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
f700: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
f710: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
f720: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
f730: 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
f740: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
f750: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  hods] object.  T
f760: 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
f770: 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  fies the interfa
f780: 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f  ce.** to a custo
f790: 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
f7a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20  lementation.)^  
f7b0: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
f7c0: 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
f7d0: 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69  bject and uses i
f7e0: 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  t for page cache
f7f0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f800: 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ons.</dd>.**.** 
f810: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
f820: 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e  G_GETPCACHE</dt>
f830: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
f840: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
f850: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
f860: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
f870: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
f880: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
f890: 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  ds] object.  SQL
f8a0: 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
f8b0: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
f8c0: 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
f8d0: 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
f8e0: 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
f8f0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
f900: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
f910: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
f920: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
f930: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
f940: 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
f950: 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
f960: 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
f970: 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
f980: 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
f990: 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
f9a0: 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
f9b0: 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
f9c0: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
f9d0: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
f9e0: 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
f9f0: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
fa00: 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
fa10: 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
fa20: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
fa30: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
fa40: 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
fa50: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
fa60: 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
fa70: 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
fa80: 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
fa90: 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
faa0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
fab0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
fac0: 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
fad0: 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
fae0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
faf0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
fb00: 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
fb10: 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
fb20: 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
fb30: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
fb40: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
fb50: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
fb60: 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
fb70: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
fb80: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
fb90: 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
fba0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
fbb0: 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
fbc0: 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
fbd0: 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
fbe0: 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
fbf0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
fc00: 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
fc10: 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
fc20: 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
fc30: 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
fc40: 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
fc50: 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
fc60: 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
fc70: 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
fc80: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
fc90: 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
fca0: 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
fcb0: 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
fcc0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
fcd0: 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
fce0: 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
fcf0: 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
fd00: 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
fd10: 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
fd20: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
fd30: 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
fd40: 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
fd50: 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
fd60: 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
fd70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
fd80: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
fd90: 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
fda0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
fdb0: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
fdc0: 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
fdd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
fde0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
fdf0: 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
fe00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fe10: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
fe20: 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
fe30: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
fe40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
fe50: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
fe60: 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
fe70: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
fe80: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
fe90: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
fea0: 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
feb0: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
fec0: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
fed0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
fee0: 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
fef0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
ff00: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
ff10: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
ff20: 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
ff30: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
ff40: 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
ff50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
ff60: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
ff70: 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
ff80: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
ff90: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
ffa0: 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
ffb0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
ffc0: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
ffd0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
ffe0: 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
fff0: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
10000 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
10010 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
10020 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
10030 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
10040 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
10050 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10060 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
10070 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
10080 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
10090 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
100a0 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73  E       14  /* s
100b0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
100c0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
100d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
100e0 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
100f0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
10100 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  he_methods* */.#
10110 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10120 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
10130 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
10140 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  void* */../*.** 
10150 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
10160 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
10170 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
10180 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
10190 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
101a0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
101b0 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
101c0 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
101d0 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
101e0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
101f0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
10200 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10210 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
10220 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
10230 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
10240 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
10250 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
10260 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
10270 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
10280 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
10290 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
102a0 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
102b0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
102c0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
102d0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
102e0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
102f0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
10300 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
10310 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
10320 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
10330 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
10340 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
10350 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
10360 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
10370 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
10380 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10390 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
103a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
103b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
103c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
103d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
103e0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
103f0 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
10400 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
10410 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
10420 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
10430 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
10440 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
10450 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
10460 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
10470 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
10480 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
10490 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
104a0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
104b0 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
104c0 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62 75   to an memory bu
104d0 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
104e0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
104f0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
10500 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
10510 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
10520 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
10530 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
10540 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
10550 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
10560 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
10570 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
10580 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
10590 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
105a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
105b0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
105c0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
105d0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
105e0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
105f0 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
10600 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
10610 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
10620 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
10630 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
10640 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
10650 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
10660 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
10670 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
10680 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
10690 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
106a0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
106b0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
106c0 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
106d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
106e0 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
106f0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
10700 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
10710 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
10720 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
10730 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
10740 6e 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20  next smaller.** 
10750 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
10760 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
10770 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
10780 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  DE]</dd>.**.** <
10790 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
107a0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
107b0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30  LOOKASIDE    100
107c0 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
107d0 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  int */.../*.** C
107e0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
107f0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
10800 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
10810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
10820 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
10830 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
10840 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
10850 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
10860 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
10870 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
10880 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
10890 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
108a0 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
108b0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
108c0 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
108d0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
108e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
108f0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
10900 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
10910 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
10920 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
10930 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
10940 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
10950 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65   an SQLite table
10960 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
10970 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
10980 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
10990 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
109a0 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
109b0 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
109c0 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
109d0 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
109e0 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
109f0 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
10a00 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
10a10 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
10a20 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
10a30 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
10a40 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
10a50 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
10a60 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
10a70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
10a80 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
10a90 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
10aa0 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
10ab0 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
10ac0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
10ad0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
10ae0 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20  id] of the most 
10af0 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73  recent.** succes
10b00 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
10b10 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
10b20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61  from the [databa
10b30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
10b40 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
10b50 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f  rgument.  ^If no
10b60 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
10b70 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76  ERT]s.** have ev
10b80 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
10b90 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
10ba0 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
10bb0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
10bc0 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
10bd0 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
10be0 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20  a trigger, then 
10bf0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
10c00 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
10c10 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ow is returned b
10c20 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61  y this routine a
10c30 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
10c40 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67  igger is running
10c50 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
10c60 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e  e trigger termin
10c70 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ates, the value 
10c80 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
10c90 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65   routine.** reve
10ca0 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20  rts to the last 
10cb0 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62  value inserted b
10cc0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
10cd0 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  r fired.)^.**.**
10ce0 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
10cf0 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
10d00 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
10d10 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
10d20 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
10d30 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
10d40 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
10d50 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
10d60 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
10d70 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
10d80 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
10d90 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
10da0 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
10db0 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
10dc0 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
10dd0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
10de0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
10df0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
10e00 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
10e10 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
10e20 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
10e30 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
10e40 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
10e50 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
10e60 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
10e70 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
10e80 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
10e90 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
10ea0 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
10eb0 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
10ec0 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
10ed0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
10ee0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
10ef0 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
10f00 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
10f10 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
10f20 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
10f30 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
10f40 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
10f50 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
10f60 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
10f70 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
10f80 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
10f90 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
10fa0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
10fb0 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
10fc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
10fd0 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
10fe0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
10ff0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
11000 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
11010 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
11020 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
11030 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
11040 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11050 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
11060 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
11070 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
11080 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
11090 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
110a0 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
110b0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
110c0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
110d0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
110e0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
110f0 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
11100 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
11110 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
11120 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
11130 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
11140 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
11150 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
11160 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
11170 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
11180 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
11190 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
111a0 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
111b0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
111c0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
111d0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
111e0 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
111f0 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
11200 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
11210 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
11220 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
11230 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
11240 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
11250 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
11260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
11270 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
11280 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
11290 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
112a0 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
112b0 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
112c0 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
112d0 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
112e0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
112f0 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
11300 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
11310 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
11320 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
11330 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
11340 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
11350 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
11360 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
11370 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
11380 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
11390 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
113a0 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
113b0 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
113c0 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
113d0 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
113e0 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
113f0 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
11400 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
11410 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
11420 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
11430 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
11440 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
11450 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
11460 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
11470 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
11480 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
11490 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
114a0 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
114b0 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
114c0 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
114d0 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
114e0 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
114f0 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
11500 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
11510 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
11520 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
11530 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
11540 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
11550 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
11560 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
11570 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
11580 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
11590 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
115a0 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
115b0 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
115c0 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
115d0 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
115e0 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
115f0 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
11600 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
11610 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
11620 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
11630 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
11640 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
11650 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
11660 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
11670 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
11680 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
11690 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
116a0 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
116b0 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
116c0 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
116d0 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
116e0 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
116f0 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
11700 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
11710 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
11720 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
11730 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
11740 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
11750 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
11760 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
11770 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
11780 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
11790 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
117a0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
117b0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
117c0 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
117d0 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
117e0 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
117f0 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
11800 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
11810 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
11820 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
11830 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
11840 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
11850 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
11860 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
11870 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
11880 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
11890 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
118a0 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
118b0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
118c0 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
118d0 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
118e0 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
118f0 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
11900 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
11910 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
11920 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
11930 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
11940 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
11950 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
11960 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
11970 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
11980 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
11990 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
119a0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
119b0 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
119c0 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
119d0 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
119e0 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
119f0 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
11a00 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
11a10 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
11a20 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
11a30 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
11a40 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
11a50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
11a60 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
11a70 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
11a80 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
11a90 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
11aa0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
11ab0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
11ac0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
11ad0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
11ae0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
11af0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11b00 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
11b10 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
11b20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
11b30 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
11b40 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
11b50 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
11b60 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
11b70 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
11b80 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
11b90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
11ba0 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
11bb0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
11bc0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
11bd0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
11be0 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
11bf0 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e  es caused by [IN
11c00 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54  SERT],.** [UPDAT
11c10 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
11c20 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
11c30 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
11c40 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
11c50 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63  ened..** ^(The c
11c60 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79  ount returned by
11c70 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
11c80 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65  hanges() include
11c90 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a  s all changes.**
11ca0 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54   from all [CREAT
11cb0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
11cc0 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e  ger] contexts an
11cd0 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62  d changes made b
11ce0 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  y.** [foreign ke
11cf0 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65  y actions]. Howe
11d00 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
11d10 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
11d20 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
11d30 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45  to implement [RE
11d40 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
11d50 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
11d60 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
11d70 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f  cessing, or [DRO
11d80 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73  P TABLE] process
11d90 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75  ing.  The.** cou
11da0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
11db0 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77  ude rows of view
11dc0 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b  s that fire an [
11dd0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
11de0 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69  er],.** though i
11df0 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46  f the INSTEAD OF
11e00 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63   trigger makes c
11e10 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77  hanges of its ow
11e20 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  n, those changes
11e30 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64   .** are counted
11e40 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .)^.** ^The sqli
11e50 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
11e60 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75  s() function cou
11e70 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20  nts the changes 
11e80 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68  as soon as.** th
11e90 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
11ea0 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63   makes them is c
11eb0 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
11ec0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
11ed0 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64  dle.** is passed
11ee0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
11ef0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
11f00 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
11f10 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
11f20 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
11f30 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
11f40 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
11f50 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
11f60 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
11f70 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
11f80 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
11f90 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
11fa0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
11fb0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
11fc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11fd0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
11fe0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
11ff0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
12000 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
12010 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
12020 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
12030 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
12040 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
12050 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
12060 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
12070 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
12080 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
12090 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
120a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
120b0 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
120c0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
120d0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
120e0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
120f0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
12100 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
12110 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
12120 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
12130 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
12140 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
12150 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
12160 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
12170 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
12180 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
12190 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
121a0 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
121b0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
121c0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
121d0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
121e0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
121f0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
12200 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
12210 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
12220 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
12230 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
12240 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
12250 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
12260 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
12270 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12280 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
12290 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
122a0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
122b0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
122c0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
122d0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
122e0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
122f0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
12300 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
12310 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
12320 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
12330 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
12340 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
12350 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
12360 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
12370 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
12380 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
12390 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
123a0 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
123b0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
123c0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
123d0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
123e0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
123f0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
12400 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
12410 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
12420 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
12430 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
12440 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
12450 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
12460 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
12470 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
12480 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
12490 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
124a0 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
124b0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
124c0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
124d0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
124e0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
124f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
12500 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
12510 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
12520 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
12530 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
12540 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
12550 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
12560 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
12570 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
12580 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
12590 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
125a0 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
125b0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
125c0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
125d0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
125e0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
125f0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
12600 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
12610 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
12620 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
12630 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
12640 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
12650 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
12660 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
12670 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
12680 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
12690 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
126a0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
126b0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
126c0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
126d0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
126e0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
126f0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
12700 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
12710 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
12720 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
12730 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
12740 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
12750 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
12760 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
12770 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
12780 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
12790 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
127a0 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
127b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
127c0 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
127d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
127e0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
127f0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
12800 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
12810 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
12820 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
12830 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
12840 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
12850 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
12860 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
12870 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
12880 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
12890 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
128a0 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
128b0 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
128c0 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
128d0 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
128e0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
128f0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
12900 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
12910 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
12920 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
12930 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
12940 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
12950 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
12960 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
12970 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
12980 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
12990 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
129a0 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
129b0 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
129c0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
129d0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
129e0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
129f0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
12a00 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
12a10 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
12a20 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
12a30 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
12a40 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
12a50 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
12a60 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
12a70 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
12a80 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
12a90 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
12aa0 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
12ab0 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
12ac0 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
12ad0 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
12ae0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
12af0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
12b00 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
12b10 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
12b20 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
12b30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
12b40 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
12b50 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
12b60 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
12b70 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
12b80 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
12b90 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
12ba0 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
12bb0 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
12bc0 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
12bd0 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
12be0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
12bf0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
12c00 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
12c10 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
12c20 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
12c30 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12c40 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
12c50 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
12c60 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
12c70 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
12c80 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
12c90 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
12ca0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
12cb0 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
12cc0 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
12cd0 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
12ce0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
12cf0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
12d00 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
12d10 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
12d20 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
12d30 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
12d40 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
12d50 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
12d60 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
12d70 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
12d80 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
12d90 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
12da0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
12db0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
12dc0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
12dd0 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
12de0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
12df0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
12e00 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
12e10 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
12e20 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
12e30 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
12e40 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
12e50 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
12e60 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
12e70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
12e80 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
12e90 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
12ea0 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
12eb0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
12ec0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
12ed0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
12ee0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
12ef0 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
12f00 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
12f10 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
12f20 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
12f30 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
12f40 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
12f50 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  locked..**.** ^I
12f60 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
12f70 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
12f80 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
12f90 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
12fa0 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
12fb0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
12fc0 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
12fd0 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
12fe0 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
12ff0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
13000 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
13010 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
13020 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
13030 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
13040 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
13050 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
13060 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
13070 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
13080 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
13090 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
130a0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
130b0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
130c0 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
130d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
130e0 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
130f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
13100 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
13110 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
13120 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
13130 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
13140 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
13150 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
13160 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
13170 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
13180 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
13190 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
131a0 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
131b0 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
131c0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
131d0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
131e0 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64  KED] is returned
131f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
13200 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
13210 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
13220 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
13230 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
13240 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
13250 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
13260 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
13270 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
13280 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
13290 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
132a0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
132b0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
132c0 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
132d0 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
132e0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
132f0 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
13300 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
13310 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
13320 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
13330 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
13340 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
13350 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
13360 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
13370 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
13380 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
13390 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
133a0 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
133b0 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
133c0 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
133d0 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
133e0 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
133f0 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
13400 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
13410 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
13420 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
13430 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
13440 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
13450 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
13460 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
13470 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
13480 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
13490 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
134a0 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
134b0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
134c0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
134d0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
134e0 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
134f0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
13500 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
13510 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
13520 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
13530 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
13540 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
13550 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
13560 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
13570 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
13580 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
13590 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
135a0 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
135b0 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
135c0 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
135d0 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
135e0 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
135f0 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
13600 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
13610 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
13620 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
13630 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
13640 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
13650 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  The [SQLITE_BUSY
13660 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65  ] error is conve
13670 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f  rted to [SQLITE_
13680 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
13690 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
136a0 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
136b0 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61  f a large transa
136c0 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20  ction where all 
136d0 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77  the.** changes w
136e0 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f  ill not fit into
136f0 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63   the in-memory c
13700 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69  ache.  SQLite wi
13710 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
13720 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
13730 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
13740 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
13750 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
13760 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
13770 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
13780 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
13790 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
137a0 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
137b0 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
137c0 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
137d0 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49  .** readers.  ^I
137e0 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
137f0 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
13800 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
13810 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
13820 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
13830 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
13840 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
13850 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
13860 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
13870 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
13880 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
13890 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
138a0 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
138b0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
138c0 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63  .  ^This error c
138d0 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
138e0 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
138f0 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
13900 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
13910 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
13920 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  f="/cvstrac/wiki
13930 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
13940 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
13950 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
13960 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
13970 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
13980 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
13990 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
139a0 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
139b0 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
139c0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
139d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
139e0 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
139f0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
13a00 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
13a10 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
13a20 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
13a30 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
13a40 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
13a50 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
13a60 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
13a70 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c  imeout()].** wil
13a80 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
13a90 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e  ear the busy han
13aa0 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
13ab0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
13ac0 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
13ad0 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
13ae0 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
13af0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13b00 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
13b10 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
13b20 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
13b30 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
13b40 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
13b50 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
13b60 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
13b70 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
13b80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13b90 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
13ba0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
13bb0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
13bc0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
13bd0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
13be0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
13bf0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
13c00 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
13c10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
13c20 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
13c30 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
13c40 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
13c50 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
13c60 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
13c70 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
13c80 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
13c90 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
13ca0 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
13cb0 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
13cc0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
13cd0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
13ce0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
13cf0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
13d00 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
13d10 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
13d20 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
13d30 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
13d40 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
13d50 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
13d60 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
13d70 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
13d80 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
13d90 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
13da0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
13db0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
13dc0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
13dd0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
13de0 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
13df0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
13e00 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
13e10 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
13e20 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
13e30 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
13e40 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
13e50 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
13e60 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
13e70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13e80 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
13e90 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
13ea0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
13eb0 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
13ec0 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
13ed0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
13ee0 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
13ef0 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
13f00 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
13f10 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
13f20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e  cleared.)^.*/.in
13f30 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
13f40 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
13f50 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
13f60 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
13f70 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
13f80 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
13f90 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ies.**.** Defini
13fa0 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
13fb0 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
13fc0 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
13fd0 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
13fe0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
13ff0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
14000 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
14010 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
14020 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
14030 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
14040 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
14050 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
14060 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
14070 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
14080 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
14090 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
140a0 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
140b0 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
140c0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
140d0 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
140e0 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
140f0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
14100 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
14110 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
14120 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
14130 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
14140 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
14150 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
14160 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
14170 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
14180 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
14190 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
141a0 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
141b0 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
141c0 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
141d0 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
141e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
141f0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
14200 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
14210 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
14220 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
14230 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
14240 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
14250 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
14260 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
14270 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
14280 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
14290 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
142a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
142b0 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
142c0 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
142d0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
142e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
142f0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
14300 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
14310 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
14320 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
14330 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
14340 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
14350 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
14360 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
14370 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
14380 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
14390 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
143a0 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
143b0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
143c0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e  ()]..**.** As an
143d0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
143e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
143f0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
14400 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
14410 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
14420 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14430 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
14440 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
14450 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
14460 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14470 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
14480 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
14490 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
144a0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
144b0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
144c0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
144d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
144e0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
144f0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
14500 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
14510 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
14520 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
14530 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
14540 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
14550 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
14560 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
14570 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
14580 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
14590 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
145a0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
145b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
145c0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
145d0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
145e0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
145f0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
14600 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
14610 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
14620 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
14630 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
14640 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
14650 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
14660 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
14670 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
14680 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
14690 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
146a0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
146b0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
146c0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
146d0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
146e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
146f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
14700 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
14710 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
14720 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
14730 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
14740 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
14750 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
14760 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
14770 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
14780 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
14790 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
147a0 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
147b0 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
147c0 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
147d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
147e0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
147f0 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
14800 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
14810 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
14820 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 73  table(),.** it s
14830 68 6f 75 6c 64 20 70 61 73 73 20 74 68 65 20 72  hould pass the r
14840 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
14850 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
14860 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
14870 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
14880 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
14890 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
148a0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
148b0 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
148c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
148d0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
148e0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
148f0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
14900 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
14910 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
14920 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
14930 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
14940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
14950 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
14960 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
14970 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
14980 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
14990 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
149a0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
149b0 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
149c0 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
149d0 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
149e0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
149f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
14a00 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
14a10 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
14a20 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
14a30 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
14a40 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
14a50 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
14a60 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
14a70 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
14a80 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
14a90 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
14aa0 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
14ab0 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
14ac0 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
14ad0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
14ae0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
14af0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
14b00 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
14b10 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
14b20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
14b30 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
14b40 33 5f 65 72 72 6d 73 67 28 29 5d 2e 29 5e 0a 2a  3_errmsg()].)^.*
14b50 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
14b60 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
14b70 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
14b80 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
14b90 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
14ba0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
14bb0 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
14bc0 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
14bd0 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
14be0 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
14bf0 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
14c00 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
14c10 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
14c20 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
14c30 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
14c40 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
14c50 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
14c60 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
14c70 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
14c80 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
14c90 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
14ca0 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
14cb0 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
14cc0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
14cd0 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
14ce0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14cf0 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
14d00 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
14d10 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
14d20 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
14d30 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
14d40 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
14d50 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
14d60 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
14d70 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
14d80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
14d90 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
14da0 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
14db0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
14dc0 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
14dd0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
14de0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
14df0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14e00 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
14e10 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
14e20 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
14e30 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
14e40 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
14e50 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
14e60 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
14e70 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
14e80 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
14e90 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
14ea0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
14eb0 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
14ec0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
14ed0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
14ee0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71 6c 69  .**.** ^(In sqli
14ef0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
14f00 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
14f10 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
14f20 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
14f30 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
14f40 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
14f50 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
14f60 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
14f70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
14f80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
14f90 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
14fa0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
14fb0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
14fc0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
14fd0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
14fe0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
14ff0 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
15000 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
15010 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
15020 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
15030 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
15040 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
15050 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
15060 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
15070 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
15080 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
15090 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
150a0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
150b0 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
150c0 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
150d0 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
150e0 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
150f0 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
15100 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
15110 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
15120 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
15130 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
15140 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
15150 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
15160 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
15170 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
15180 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
15190 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
151a0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
151b0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
151c0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
151d0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
151e0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
151f0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
15200 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
15210 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
15220 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
15230 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
15240 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
15250 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
15260 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
15270 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
15280 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
15290 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
152a0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
152b0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
152c0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
152d0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
152e0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
152f0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
15300 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  rs..**.** These 
15310 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
15320 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
15330 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
15340 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
15350 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
15360 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
15370 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
15380 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
15390 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
153a0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
153b0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
153c0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
153d0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
153e0 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
153f0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
15400 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
15410 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
15420 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
15430 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ll-terminated.**
15440 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
15450 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
15460 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
15470 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
15480 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
15490 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
154a0 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
154b0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
154c0 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
154d0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
154e0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
154f0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
15500 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
15510 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
15520 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
15530 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
15540 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
15550 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
15560 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
15570 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
15580 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
15590 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
155a0 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
155b0 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
155c0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
155d0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
155e0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
155f0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
15600 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
15610 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
15620 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
15630 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
15640 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
15650 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
15660 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
15670 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
15680 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
15690 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
156a0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
156b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
156c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
156d0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
156e0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
156f0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
15700 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
15710 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
15720 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
15730 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
15740 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
15750 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
15760 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
15770 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
15780 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
15790 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
157a0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
157b0 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
157c0 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
157d0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
157e0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
157f0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
15800 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
15810 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
15820 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
15830 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
15840 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
15850 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
15860 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
15870 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
15880 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
15890 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
158a0 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
158b0 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
158c0 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
158d0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
158e0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
158f0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
15900 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
15910 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
15920 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
15930 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
15940 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
15950 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
15960 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
15970 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
15980 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
15990 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
159a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
159b0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
159c0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
159d0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
159e0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
159f0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
15a00 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
15a10 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
15a20 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
15a30 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
15a40 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
15a50 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
15a60 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
15a70 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
15a80 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
15a90 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
15aa0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
15ab0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
15ac0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
15ad0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
15ae0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
15af0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
15b00 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
15b10 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
15b20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
15b30 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
15b40 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
15b50 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
15b60 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
15b70 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
15b80 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
15b90 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
15ba0 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
15bb0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
15bc0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
15bd0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
15be0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
15bf0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
15c00 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
15c10 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
15c20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
15c30 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
15c40 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
15c50 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
15c60 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
15c70 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
15c80 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
15c90 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
15ca0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
15cb0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
15cc0 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
15cd0 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
15ce0 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
15cf0 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
15d00 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
15d10 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
15d20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15d30 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
15d40 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
15d50 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
15d60 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
15d70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
15d80 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
15d90 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
15da0 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
15db0 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
15dc0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
15dd0 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
15de0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
15df0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15e00 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
15e10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
15e20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
15e30 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
15e40 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
15e50 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
15e60 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
15e70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15e80 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
15e90 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
15ea0 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
15eb0 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
15ec0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
15ed0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
15ee0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
15ef0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
15f00 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
15f10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15f20 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
15f30 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
15f40 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
15f50 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
15f60 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
15f70 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
15f80 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
15f90 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
15fa0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
15fb0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
15fc0 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
15fd0 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
15fe0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
15ff0 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
16000 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
16010 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
16020 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
16030 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
16040 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
16050 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
16060 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
16070 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
16080 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
16090 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
160a0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
160b0 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
160c0 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
160d0 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
160e0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
160f0 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
16100 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
16110 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
16120 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
16130 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
16140 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
16150 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
16160 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
16170 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
16180 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
16190 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
161a0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
161b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
161c0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
161d0 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
161e0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
161f0 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
16200 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
16210 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
16220 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
16230 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
16240 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
16250 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
16260 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
16270 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16280 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
16290 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
162a0 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
162b0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
162c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
162d0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
162e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
162f0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
16300 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
16310 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
16320 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
16330 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
16340 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
16350 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
16360 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
16370 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16380 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
16390 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
163a0 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
163b0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
163c0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
163d0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
163e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
163f0 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
16400 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
16410 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
16420 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
16430 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
16440 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
16450 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
16460 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
16470 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
16480 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
16490 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
164a0 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
164b0 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
164c0 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
164d0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
164e0 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
164f0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
16500 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
16510 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
16520 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
16530 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
16540 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
16550 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
16560 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
16570 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
16580 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16590 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
165a0 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
165b0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
165c0 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
165d0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
165e0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
165f0 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
16600 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
16610 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
16620 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
16630 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
16640 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  ary..**.** In SQ
16650 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
16660 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
16670 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
16680 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
16690 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
166a0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
166b0 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
166c0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
166d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
166e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
166f0 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
16700 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
16710 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
16720 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
16730 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
16740 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
16750 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
16760 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
16770 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
16780 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ls.** the system
16790 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
167a0 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
167b0 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
167c0 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
167d0 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
167e0 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
167f0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
16800 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
16810 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
16820 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
16830 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
16840 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
16850 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
16860 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ors are detected
16870 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72  , but.** they ar
16880 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
16890 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
168a0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
168b0 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
168c0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
168d0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
168e0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
168f0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
16900 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
16910 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
16920 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
16930 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
16940 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
16950 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
16960 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
16970 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
16980 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
16990 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
169a0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
169b0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
169c0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
169d0 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
169e0 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
169f0 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
16a00 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
16a10 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
16a20 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
16a30 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
16a40 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
16a50 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
16a60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
16a70 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
16a80 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
16a90 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
16aa0 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
16ab0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16ac0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
16ad0 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
16ae0 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
16af0 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
16b00 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
16b10 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
16b20 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
16b30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16b40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
16b50 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
16b60 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
16b70 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
16b80 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
16b90 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
16ba0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
16bb0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
16bc0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
16bd0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
16be0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
16bf0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
16c00 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
16c10 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
16c20 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
16c30 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
16c40 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
16c50 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
16c60 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
16c70 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
16c80 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
16c90 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
16ca0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
16cb0 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
16cc0 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
16cd0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
16ce0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
16cf0 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
16d00 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
16d10 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
16d20 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
16d30 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
16d40 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
16d50 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
16d60 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
16d70 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
16d80 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
16d90 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
16da0 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
16db0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
16dc0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16dd0 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
16de0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
16df0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
16e00 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
16e10 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
16e20 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
16e30 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
16e40 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
16e50 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
16e60 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
16e70 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
16e80 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
16e90 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
16ea0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
16eb0 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
16ec0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
16ed0 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
16ee0 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
16ef0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
16f00 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
16f10 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
16f20 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
16f30 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
16f40 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
16f50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
16f60 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
16f70 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
16f80 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
16f90 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
16fa0 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
16fb0 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
16fc0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
16fd0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
16fe0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
16ff0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
17000 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
17010 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
17020 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
17030 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
17040 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
17050 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
17060 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
17070 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
17080 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
17090 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
170a0 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
170b0 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
170c0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
170d0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
170e0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
170f0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
17100 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
17110 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
17120 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
17130 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
17140 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
17150 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ime this routine
17160 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74   is invoked (eit
17170 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f  her internally o
17180 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c  r by.** the appl
17190 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e  ication) the PRN
171a0 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e  G is seeded usin
171b0 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
171c0 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68  ained.** from th
171d0 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
171e0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
171f0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
17200 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e  ] object..** ^On
17210 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
17220 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
17230 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
17240 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
17250 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
17260 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
17270 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
17280 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
17290 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
172a0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
172b0 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
172c0 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
172d0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
172e0 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
172f0 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
17300 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
17310 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
17320 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17330 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
17340 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
17350 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
17360 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
17370 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
17380 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
17390 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
173a0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
173b0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
173c0 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
173d0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
173e0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
173f0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
17400 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
17410 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
17420 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
17430 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
17440 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
17450 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
17460 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
17470 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
17480 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
17490 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
174a0 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
174b0 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
174c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
174d0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
174e0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
174f0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
17500 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
17510 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
17520 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
17530 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
17540 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
17550 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
17560 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
17570 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
17580 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
17590 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
175a0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
175b0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
175c0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
175d0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
175e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
175f0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
17600 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
17610 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
17620 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
17630 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
17640 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
17650 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
17660 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
17670 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
17680 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
17690 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
176a0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
176b0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
176c0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
176d0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
176e0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
176f0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
17700 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
17710 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
17720 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
17730 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
17740 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
17750 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
17760 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
17770 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
17780 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17790 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
177a0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
177b0 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
177c0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
177d0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
177e0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
177f0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
17800 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
17810 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
17820 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17830 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17840 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
17850 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
17860 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
17870 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
17880 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
17890 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
178a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
178b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
178c0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
178d0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
178e0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
178f0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
17900 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
17910 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
17920 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
17930 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
17940 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
17950 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
17960 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
17970 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
17980 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
17990 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
179a0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
179b0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
179c0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
179d0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
179e0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
179f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17a00 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
17a10 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
17a20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
17a30 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
17a40 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
17a50 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
17a60 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
17a70 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
17a80 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
17a90 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
17aa0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
17ab0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
17ac0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
17ad0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
17ae0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
17af0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
17b00 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
17b10 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
17b20 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
17b30 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
17b40 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
17b50 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
17b60 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
17b70 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
17b80 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
17b90 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
17ba0 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
17bb0 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
17bc0 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
17bd0 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
17be0 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
17bf0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
17c00 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
17c10 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
17c20 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
17c30 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
17c40 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
17c50 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
17c60 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
17c70 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
17c80 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
17c90 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
17ca0 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
17cb0 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
17cc0 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
17cd0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
17ce0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
17cf0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
17d00 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
17d10 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
17d20 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
17d30 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
17d40 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
17d50 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
17d60 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
17d70 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
17d80 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
17d90 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
17da0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
17db0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
17dc0 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
17dd0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
17de0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
17df0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
17e00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
17e10 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
17e20 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
17e30 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
17e40 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
17e50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
17e60 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
17e70 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
17e80 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
17e90 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
17ea0 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
17eb0 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
17ec0 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
17ed0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
17ee0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
17ef0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
17f00 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
17f10 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
17f20 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
17f30 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
17f40 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
17f50 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
17f60 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
17f70 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
17f80 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
17f90 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
17fa0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
17fb0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
17fc0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
17fd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17fe0 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
17ff0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
18000 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18010 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
18020 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
18030 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
18040 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
18050 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
18060 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
18070 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
18080 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
18090 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
180a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
180b0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
180c0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
180d0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
180e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
180f0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
18100 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
18110 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
18120 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
18130 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
18140 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
18150 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
18160 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
18170 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
18180 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
18190 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
181a0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
181b0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
181c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
181d0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
181e0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
181f0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
18200 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
18210 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
18220 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
18230 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
18240 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
18250 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
18260 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
18270 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
18280 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
18290 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
182a0 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
182b0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
182c0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
182d0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
182e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
182f0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
18300 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
18310 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
18320 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
18330 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
18340 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
18350 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
18360 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
18370 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
18380 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
18390 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
183a0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
183b0 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
183c0 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
183d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
183e0 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
183f0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
18400 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
18410 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
18420 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
18430 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
18440 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
18450 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
18460 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
18470 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
18480 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
18490 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
184a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
184b0 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
184c0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
184d0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
184e0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
184f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
18500 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
18510 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
18520 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
18530 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
18540 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
18550 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
18560 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
18570 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
18580 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
18590 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
185a0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
185b0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
185c0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
185d0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
185e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
185f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18600 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
18610 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
18620 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
18630 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
18640 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
18650 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
18660 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
18670 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
18680 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
18690 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
186a0 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
186b0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
186c0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
186d0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
186e0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
186f0 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
18700 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
18710 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
18720 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
18730 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
18740 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
18750 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
18760 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
18770 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
18780 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
18790 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
187a0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
187b0 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
187c0 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
187d0 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
187e0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
187f0 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
18800 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
18810 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
18820 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
18830 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
18840 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
18850 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
18860 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
18870 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
18880 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
18890 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
188a0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
188b0 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
188c0 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
188d0 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
188e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
188f0 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
18900 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
18910 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
18920 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
18930 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
18940 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
18950 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
18960 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
18970 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
18980 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
18990 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
189a0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
189b0 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
189c0 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
189d0 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
189e0 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
189f0 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
18a00 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
18a10 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
18a20 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
18a30 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
18a40 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
18a50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18a60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18a70 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
18a80 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
18a90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
18aa0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18ab0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
18ac0 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
18ad0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
18ae0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18af0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18b00 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
18b10 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18b20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18b30 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18b40 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
18b50 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
18b60 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
18b70 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
18b80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18b90 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
18ba0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
18bb0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18bc0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18bd0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18be0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
18bf0 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
18c00 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
18c10 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
18c20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18c30 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
18c40 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
18c50 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
18c60 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18c70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18c80 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
18c90 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
18ca0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
18cb0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18cc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18cd0 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
18ce0 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
18cf0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
18d00 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18d10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18d20 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
18d30 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
18d40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
18d50 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18d60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18d70 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
18d80 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
18d90 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
18da0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18db0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18dc0 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
18dd0 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
18de0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
18df0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18e00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18e10 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
18e20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
18e30 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
18e40 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18e50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
18e60 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
18e70 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
18e80 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
18e90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18ea0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
18eb0 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
18ec0 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
18ed0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
18ee0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
18ef0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
18f00 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
18f10 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
18f20 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
18f30 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18f40 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
18f50 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
18f60 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
18f70 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
18f80 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
18f90 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
18fa0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
18fb0 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
18fc0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
18fd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18fe0 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
18ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
19000 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
19010 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19020 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19030 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
19040 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
19050 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
19060 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
19070 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
19080 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
19090 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
190a0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
190b0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
190c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
190d0 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
190e0 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
190f0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
19100 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19110 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19120 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
19130 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
19140 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
19150 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19160 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19170 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
19180 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
19190 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
191a0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
191b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
191c0 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
191d0 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
191e0 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
191f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19200 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19210 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
19220 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
19230 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
19240 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19250 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19260 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
19270 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
19280 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
19290 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
192a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
192b0 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
192c0 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
192d0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
192e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
192f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
19300 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
19310 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
19320 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
19330 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19340 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19350 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
19360 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
19370 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
19380 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
19390 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
193a0 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
193b0 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
193c0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
193d0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
193e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
193f0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
19400 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
19410 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
19420 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
19430 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
19440 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
19450 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
19460 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
19470 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
19480 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
19490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
194a0 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
194b0 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
194c0 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
194d0 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
194e0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
194f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
19500 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
19510 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
19520 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
19530 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
19540 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
19550 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
19560 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
19570 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
19580 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
19590 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
195a0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
195b0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
195c0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
195d0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
195e0 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
195f0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
19600 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
19610 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
19620 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
19630 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
19640 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
19650 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
19660 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
19670 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
19680 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
19690 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
196a0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
196b0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
196c0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
196d0 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
196e0 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
196f0 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
19700 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
19710 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
19720 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
19730 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
19740 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
19750 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
19760 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
19770 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
19780 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
19790 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
197a0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
197b0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
197c0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
197d0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
197e0 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
197f0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
19800 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
19810 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
19820 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
19830 20 74 6f 20 72 75 6e 2e 0a 2a 2f 0a 76 6f 69 64   to run..*/.void
19840 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
19850 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
19860 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
19870 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
19880 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
19890 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
198a0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
198b0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
198c0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
198d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
198e0 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
198f0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
19900 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
19910 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
19920 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
19930 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61  ine configures a
19940 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
19950 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67  on - the.** prog
19960 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20  ress callback - 
19970 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
19980 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
19990 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e  ing long.** runn
199a0 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ing calls to [sq
199b0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
199c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
199d0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
199e0 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41  get_table()].  A
199f0 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
19a00 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
19a10 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
19a20 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
19a30 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
19a40 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
19a50 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
19a60 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
19a70 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
19a80 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
19a90 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
19aa0 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
19ab0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
19ac0 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
19ad0 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
19ae0 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
19af0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
19b00 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  ss handler must 
19b10 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
19b20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
19b30 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
19b40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
19b50 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
19b60 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
19b70 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
19b80 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
19b90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
19ba0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
19bb0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
19bc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19bd0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
19be0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
19bf0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
19c00 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
19c10 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
19c20 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
19c30 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
19c40 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
19c50 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
19c60 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
19c70 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
19c80 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
19c90 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
19ca0 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
19cb0 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67   whose name is g
19cc0 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66  iven by the.** f
19cd0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
19ce0 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
19cf0 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
19d00 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
19d10 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
19d20 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
19d30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
19d40 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
19d50 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
19d60 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
19d70 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
19d80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
19d90 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
19da0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
19db0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
19dc0 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
19dd0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
19de0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
19df0 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
19e00 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
19e10 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
19e20 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
19e30 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
19e40 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
19e50 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
19e60 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
19e70 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
19e80 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
19e90 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
19ea0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
19eb0 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
19ec0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
19ed0 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
19ee0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
19ef0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
19f00 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
19f10 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
19f20 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
19f30 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
19f40 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
19f50 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
19f60 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
19f70 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
19f80 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
19f90 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
19fa0 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
19fb0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
19fc0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
19fd0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
19fe0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
19ff0 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
1a000 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
1a010 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
1a020 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
1a030 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1a040 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
1a050 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1a060 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
1a070 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
1a080 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
1a090 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
1a0a0 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
1a0b0 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
1a0c0 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
1a0d0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1a0e0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
1a0f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1a100 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
1a110 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
1a120 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
1a130 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
1a140 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
1a150 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1a160 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
1a170 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
1a180 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
1a190 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
1a1a0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
1a1b0 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
1a1c0 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
1a1d0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
1a1e0 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
1a1f0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1a200 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
1a210 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
1a220 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
1a230 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
1a240 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
1a250 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
1a260 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
1a270 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
1a280 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
1a290 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
1a2a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1a2b0 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
1a2c0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1a2d0 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  HE],.** and/or [
1a2e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1a2f0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73 3a  ATECACHE] flags:
1a300 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
1a310 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1a320 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
1a330 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1a340 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1a350 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
1a360 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
1a370 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1a380 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1a390 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1a3a0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
1a3b0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1a3c0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1a3d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1a3e0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1a3f0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1a400 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
1a410 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
1a420 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
1a430 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
1a440 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
1a450 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1a460 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
1a470 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
1a480 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
1a490 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
1a4a0 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
1a4b0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
1a4c0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
1a4d0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1a4e0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
1a4f0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
1a500 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1a510 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1a520 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1a530 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
1a540 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74  ates it if.** it
1a550 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
1a560 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
1a570 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
1a580 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
1a590 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
1a5a0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1a5b0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
1a5c0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
1a5d0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1a5e0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1a5f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1a600 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1a610 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1a620 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f  shown above or o
1a630 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e  ne of the combin
1a640 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1a650 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77  ve combined.** w
1a660 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
1a670 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
1a680 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1a690 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  MUTEX],.** [SQLI
1a6a0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1a6b0 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  CHE] and/or [SQL
1a6c0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1a6d0 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20  ACHE] flags,.** 
1a6e0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1a6f0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
1a700 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
1a710 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1a720 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
1a730 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1a740 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1a750 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
1a760 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
1a770 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
1a780 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
1a790 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
1a7a0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
1a7b0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
1a7c0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
1a7d0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
1a7e0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1a7f0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1a800 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1a810 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
1a820 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
1a830 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
1a840 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
1a850 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
1a860 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
1a870 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
1a880 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
1a890 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
1a8a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
1a8b0 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
1a8c0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
1a8d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1a8e0 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
1a8f0 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
1a900 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
1a910 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1a920 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
1a930 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
1a940 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
1a950 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
1a960 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
1a970 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
1a980 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
1a990 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
1a9a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a9b0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
1a9c0 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
1a9d0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1a9e0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
1a9f0 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nabled..**.** ^I
1aa00 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1aa10 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
1aa20 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1aa30 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
1aa40 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
1aa50 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
1aa60 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
1aa70 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
1aa80 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
1aa90 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
1aaa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1aab0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
1aac0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1aad0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1aae0 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
1aaf0 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
1ab00 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
1ab10 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
1ab20 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
1ab30 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
1ab40 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
1ab50 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1ab60 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
1ab70 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
1ab80 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
1ab90 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
1aba0 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
1abb0 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
1abc0 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
1abd0 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
1abe0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1abf0 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
1ac00 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
1ac10 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1ac20 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
1ac30 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1ac40 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
1ac50 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
1ac60 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
1ac70 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
1ac80 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
1ac90 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1aca0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1acb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
1acc0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1acd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ace0 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
1acf0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1ad00 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
1ad10 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
1ad20 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
1ad30 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
1ad40 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1ad50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
1ad60 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
1ad70 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1ad80 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
1ad90 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
1ada0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1adb0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
1adc0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   used..**.** <b>
1add0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
1ade0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
1adf0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
1ae00 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
1ae10 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
1ae20 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1ae30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ae40 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
1ae50 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
1ae60 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
1ae70 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
1ae80 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
1ae90 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
1aea0 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
1aeb0 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
1aec0 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
1aed0 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
1aee0 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
1aef0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1af00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1af10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1af20 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
1af30 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
1af40 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1af50 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
1af60 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1af70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1af80 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1af90 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
1afa0 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
1afb0 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
1afc0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1afd0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1afe0 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
1aff0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
1b000 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1b010 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
1b020 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1b030 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
1b040 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
1b050 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1b060 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
1b070 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1b080 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
1b090 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1b0a0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
1b0b0 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
1b0c0 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
1b0d0 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
1b0e0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
1b0f0 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
1b100 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
1b110 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
1b120 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
1b130 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
1b140 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1b150 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1b160 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
1b170 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
1b180 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
1b190 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
1b1a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
1b1b0 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
1b1c0 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
1b1d0 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
1b1e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b1f0 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
1b200 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
1b210 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
1b220 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
1b230 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
1b240 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
1b250 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
1b260 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
1b270 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
1b280 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1b290 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
1b2a0 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
1b2b0 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
1b2c0 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
1b2d0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
1b2e0 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
1b2f0 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
1b300 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
1b310 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
1b320 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
1b330 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
1b340 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
1b350 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
1b360 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
1b370 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
1b380 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
1b390 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
1b3a0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
1b3b0 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
1b3c0 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
1b3d0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
1b3e0 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
1b3f0 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
1b400 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
1b410 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
1b420 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
1b430 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
1b440 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
1b450 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
1b460 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
1b470 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
1b480 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1b490 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
1b4a0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
1b4b0 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ns.)^.**.** When
1b4c0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
1b4d0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1b4e0 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
1b4f0 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
1b500 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
1b510 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
1b520 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
1b530 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
1b540 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
1b550 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
1b560 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
1b570 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
1b580 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
1b590 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
1b5a0 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
1b5b0 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
1b5c0 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
1b5d0 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
1b5e0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
1b5f0 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
1b600 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
1b610 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
1b620 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
1b630 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
1b640 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
1b650 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
1b660 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
1b670 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
1b680 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
1b690 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
1b6a0 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
1b6b0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
1b6c0 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
1b6d0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
1b6e0 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
1b6f0 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
1b700 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
1b710 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
1b720 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
1b730 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
1b740 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
1b750 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
1b760 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
1b770 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
1b780 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
1b790 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
1b7a0 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
1b7b0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
1b7c0 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
1b7d0 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f  y not be set..*/
1b7e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
1b7f0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
1b800 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
1b810 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
1b820 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
1b830 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1b840 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
1b850 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
1b860 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1b870 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1b880 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
1b890 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
1b8a0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
1b8b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1b8c0 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
1b8d0 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
1b8e0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
1b8f0 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
1b900 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
1b910 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
1b920 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
1b930 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
1b940 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
1b950 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
1b960 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
1b970 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
1b980 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
1b990 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
1b9a0 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
1b9b0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
1b9c0 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
1b9d0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
1b9e0 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
1b9f0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1ba00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ba10 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
1ba20 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
1ba30 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
1ba40 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
1ba50 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
1ba60 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
1ba70 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
1ba80 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
1ba90 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
1baa0 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
1bab0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
1bac0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
1bad0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
1bae0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
1baf0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
1bb00 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
1bb10 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
1bb20 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
1bb30 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
1bb40 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
1bb50 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
1bb60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1bb70 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
1bb80 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
1bb90 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
1bba0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
1bbb0 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
1bbc0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1bbd0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
1bbe0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1bbf0 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
1bc00 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
1bc10 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
1bc20 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
1bc30 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
1bc40 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
1bc50 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
1bc60 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
1bc70 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
1bc80 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
1bc90 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
1bca0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1bcb0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
1bcc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1bcd0 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
1bce0 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
1bcf0 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
1bd00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
1bd10 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
1bd20 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
1bd30 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
1bd40 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
1bd50 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
1bd60 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
1bd70 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
1bd80 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
1bd90 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
1bda0 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74  ruct.  The funct
1bdb0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1bdc0 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a 2a 0a  old limit.)^.**.
1bdd0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
1bde0 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
1bdf0 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
1be00 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
1be10 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74 68 65 20  d..** ^(For the 
1be20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f  limit category o
1be30 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58  f SQLITE_LIMIT_X
1be40 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  YZ there is a .*
1be50 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
1be60 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
1be70 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c   set by a compil
1be80 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63  e-time C preproc
1be90 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65  essor macro name
1bea0 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  d .** [limits | 
1beb0 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e  SQLITE_MAX_XYZ].
1bec0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
1bed0 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
1bee0 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
1bef0 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
1bf00 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
1bf10 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
1bf20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
1bf30 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
1bf40 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
1bf50 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
1bf60 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 52 75   bound..**.** Ru
1bf70 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
1bf80 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
1bf90 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
1bfa0 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
1bfb0 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
1bfc0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
1bfd0 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
1bfe0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
1bff0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
1c000 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
1c010 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
1c020 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
1c030 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
1c040 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
1c050 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
1c060 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
1c070 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
1c080 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
1c090 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
1c0a0 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
1c0b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
1c0c0 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
1c0d0 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
1c0e0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
1c0f0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
1c100 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
1c110 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
1c120 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
1c130 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
1c140 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
1c150 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
1c160 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
1c170 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
1c180 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
1c190 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
1c1a0 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
1c1b0 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
1c1c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
1c1d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
1c1e0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
1c1f0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
1c200 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
1c210 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
1c220 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
1c230 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
1c240 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
1c250 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
1c260 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
1c270 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1c280 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
1c290 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
1c2a0 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
1c2b0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
1c2c0 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
1c2d0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
1c2e0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
1c2f0 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
1c300 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1c310 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
1c320 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
1c330 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
1c340 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
1c350 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
1c360 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
1c370 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
1c380 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
1c390 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
1c3a0 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
1c3b0 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
1c3c0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
1c3d0 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
1c3e0 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
1c3f0 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
1c400 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
1c410 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
1c420 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
1c430 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
1c440 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
1c450 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
1c460 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53   <dl>.** ^(<dt>S
1c470 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1c480 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1c490 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
1c4a0 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
1c4b0 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
1c4c0 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  ow.<dd>)^.**.** 
1c4d0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1c4e0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
1c4f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c500 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1c510 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1c520 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  , in bytes.</dd>
1c530 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1c540 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1c550 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
1c560 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1c570 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1c580 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
1c590 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
1c5a0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
1c5b0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
1c5c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1c5d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
1c5e0 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
1c5f0 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
1c600 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
1c610 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1c620 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
1c630 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
1c640 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c650 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
1c660 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
1c670 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
1c680 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1c690 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1c6a0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
1c6b0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c6c0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
1c6d0 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
1c6e0 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
1c6f0 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
1c700 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1c710 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
1c720 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c730 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
1c740 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
1c750 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
1c760 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
1c770 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
1c780 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c   SQL statement.<
1c790 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1c7a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c7b0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
1c7c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c7d0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
1c7e0 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
1c7f0 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
1c800 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1c810 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
1c820 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c830 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c840 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
1c850 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
1c860 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e  .)^</dd>.**.** ^
1c870 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1c880 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1c890 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1c8a0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
1c8b0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
1c8c0 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
1c8d0 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
1c8e0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
1c8f0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
1c900 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1c910 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1c920 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
1c930 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1c940 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69  r of variables i
1c950 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1c960 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62  nt that can.** b
1c970 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 29 5e 0a  e bound.</dd>)^.
1c980 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1c990 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
1c9a0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
1c9b0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
1c9c0 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
1c9d0 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
1c9e0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
1c9f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ca00 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
1ca10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ca20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
1ca30 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
1ca40 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
1ca50 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
1ca60 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
1ca70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ca80 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
1ca90 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
1caa0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
1cab0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
1cac0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
1cad0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
1cae0 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
1caf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
1cb00 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
1cb10 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
1cb20 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
1cb30 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
1cb40 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
1cb50 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
1cb60 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
1cb70 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
1cb80 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1cb90 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
1cba0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
1cbb0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1cbc0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1cbd0 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
1cbe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1cbf0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
1cc00 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f             10../
1cc10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1cc20 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
1cc30 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
1cc40 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
1cc50 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
1cc60 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
1cc70 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
1cc80 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
1cc90 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
1cca0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
1ccb0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
1ccc0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1ccd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
1cce0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
1ccf0 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
1cd00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
1cd10 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
1cd20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
1cd30 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1cd40 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1cd50 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
1cd60 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
1cd70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
1cd80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cd90 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
1cda0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
1cdb0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
1cdc0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
1cdd0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
1cde0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
1cdf0 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
1ce00 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
1ce10 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
1ce20 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
1ce30 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1ce40 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
1ce50 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
1ce60 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1ce70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
1ce80 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1ce90 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
1cea0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1ceb0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
1cec0 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
1ced0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
1cee0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
1cef0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1cf00 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
1cf10 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
1cf20 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
1cf30 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d  e maximum.** num
1cf40 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65  ber of  bytes re
1cf50 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
1cf60 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
1cf70 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
1cf80 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
1cf90 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
1cfa0 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
1cfb0 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
1cfc0 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
1cfd0 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
1cfe0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
1cff0 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
1d000 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
1d010 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
1d020 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
1d030 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
1d040 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
1d050 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
1d060 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
1d070 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
1d080 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
1d090 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
1d0a0 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
1d0b0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
1d0c0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
1d0d0 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
1d0e0 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
1d0f0 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a  ator bytes..**.*
1d100 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
1d110 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
1d120 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
1d130 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
1d140 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
1d150 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
1d160 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
1d170 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
1d180 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
1d190 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
1d1a0 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
1d1b0 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
1d1c0 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
1d1d0 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
1d1e0 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
1d1f0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
1d200 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
1d210 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
1d220 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
1d230 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
1d240 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
1d250 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
1d260 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
1d270 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
1d280 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
1d290 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
1d2a0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
1d2b0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
1d2c0 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
1d2d0 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
1d2e0 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
1d2f0 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
1d300 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
1d310 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
1d320 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
1d330 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
1d340 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
1d350 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1d360 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1d370 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
1d380 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
1d390 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
1d3a0 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
1d3b0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
1d3c0 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
1d3d0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
1d3e0 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
1d3f0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
1d400 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
1d410 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
1d420 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
1d430 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1d440 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
1d450 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1d460 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
1d470 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
1d480 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
1d490 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
1d4a0 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
1d4b0 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
1d4c0 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
1d4d0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1d4e0 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
1d4f0 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
1d500 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
1d510 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
1d520 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
1d530 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
1d540 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
1d550 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
1d560 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
1d570 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
1d580 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
1d590 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
1d5a0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1d5b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
1d5c0 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
1d5d0 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
1d5e0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
1d5f0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
1d600 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
1d610 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
1d620 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
1d630 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1d640 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
1d650 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
1d660 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1d670 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
1d680 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
1d690 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
1d6a0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
1d6b0 74 20 61 67 61 69 6e 2e 20 20 5e 49 66 20 74 68  t again.  ^If th
1d6c0 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61  e schema has cha
1d6d0 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79  nged in.** a way
1d6e0 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20   that makes the 
1d6f0 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e  statement no lon
1d700 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69  ger valid, [sqli
1d710 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1d720 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e   still.** return
1d730 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1d740 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68  .  But unlike th
1d750 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
1d760 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  r, [SQLITE_SCHEM
1d770 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66  A] is.** now a f
1d780 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c  atal error.  Cal
1d790 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  ling [sqlite3_pr
1d7a0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69  epare_v2()] agai
1d7b0 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20  n will not make 
1d7c0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20  the.** error go 
1d7d0 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65  away.  Note: use
1d7e0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1d7f0 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ()] to find the 
1d800 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70  text.** of the p
1d810 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61  arsing error tha
1d820 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20  t results in an 
1d830 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1d840 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e  return..** </li>
1d850 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
1d860 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
1d870 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
1d880 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
1d890 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
1d8a0 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
1d8b0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
1d8c0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
1d8d0 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
1d8e0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
1d8f0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
1d900 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
1d910 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
1d920 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
1d930 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
1d940 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
1d950 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
1d960 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
1d970 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1d980 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
1d990 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
1d9a0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
1d9b0 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
1d9c0 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
1d9d0 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
1d9e0 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
1d9f0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
1da00 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
1da10 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1da20 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
1da30 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
1da40 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 5b  the value of a [
1da50 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
1da60 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
1da70 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
1da80 6d 69 67 68 74 0a 2a 2a 20 63 68 61 6e 67 65 20  might.** change 
1da90 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 20 66  the query plan f
1daa0 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  or a statement, 
1dab0 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
1dac0 6e 74 20 6d 61 79 20 62 65 0a 2a 2a 20 61 75 74  nt may be.** aut
1dad0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1dae0 70 69 6c 65 64 20 28 61 73 20 69 66 20 74 68 65  piled (as if the
1daf0 72 65 20 68 61 64 20 62 65 65 6e 20 61 20 73 63  re had been a sc
1db00 68 65 6d 61 20 63 68 61 6e 67 65 29 20 6f 6e 20  hema change) on 
1db10 74 68 65 20 66 69 72 73 74 20 0a 2a 2a 20 5b 73  the first .** [s
1db20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
1db30 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
1db40 79 20 63 68 61 6e 67 65 20 74 6f 20 74 68 65 20  y change to the 
1db50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1db60 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
1db70 73 5d 20 6f 66 20 74 68 65 20 5b 70 61 72 61 6d  s] of the [param
1db80 65 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c 69 3e  eter]. .** </li>
1db90 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ol>.*/.int
1dba0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1dbb0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1dbc0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1dbd0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1dbe0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1dbf0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1dc00 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1dc10 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1dc20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1dc30 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1dc40 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1dc50 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1dc60 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1dc70 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1dc80 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1dc90 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1dca0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1dcb0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1dcc0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1dcd0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1dce0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1dcf0 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
1dd00 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1dd10 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1dd20 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1dd30 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1dd40 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1dd50 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1dd60 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1dd70 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1dd80 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1dd90 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1dda0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1ddb0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1ddc0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1ddd0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1dde0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1ddf0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1de00 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1de10 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1de20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1de30 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
1de40 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1de50 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1de60 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1de70 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1de80 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1de90 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1dea0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1deb0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1dec0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1ded0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1dee0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1def0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1df00 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1df10 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1df20 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1df30 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1df40 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1df50 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1df60 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1df70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1df80 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
1df90 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1dfa0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1dfb0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1dfc0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
1dfd0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1dfe0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
1dff0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1e000 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1e010 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1e020 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1e030 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1e040 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1e050 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1e060 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1e070 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
1e080 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1e090 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1e0a0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1e0b0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1e0c0 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
1e0d0 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
1e0e0 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
1e0f0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
1e100 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
1e110 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
1e120 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
1e130 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
1e140 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
1e150 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
1e160 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
1e170 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
1e180 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1e190 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e1a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
1e1b0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1e1c0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1e1d0 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
1e1e0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1e1f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e200 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
1e210 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
1e220 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
1e230 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1e240 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
1e250 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1e260 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
1e270 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
1e280 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
1e290 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
1e2a0 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
1e2b0 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
1e2c0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
1e2d0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
1e2e0 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
1e2f0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
1e300 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
1e310 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
1e320 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1e330 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
1e340 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
1e350 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
1e360 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
1e370 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
1e380 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1e390 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
1e3a0 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
1e3b0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
1e3c0 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
1e3d0 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
1e3e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1e3f0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
1e400 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
1e410 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
1e420 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
1e430 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1e440 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
1e450 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
1e460 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
1e470 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
1e480 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
1e490 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
1e4a0 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
1e4b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1e4c0 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
1e4d0 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
1e4e0 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
1e4f0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
1e500 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
1e510 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
1e520 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65   A internal mute
1e530 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
1e540 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1e550 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e560 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
1e570 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
1e580 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1e590 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e5a0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
1e5b0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
1e5c0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
1e5d0 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
1e5e0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
1e5f0 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
1e600 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
1e610 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
1e620 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
1e630 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
1e640 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
1e650 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
1e660 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
1e670 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
1e680 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
1e690 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
1e6a0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
1e6b0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
1e6c0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
1e6d0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1e6e0 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
1e6f0 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
1e700 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
1e710 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
1e720 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
1e730 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
1e740 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1e750 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
1e760 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
1e770 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
1e780 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72  tween between pr
1e790 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1e7a0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1e7b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1e7c0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
1e7d0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
1e7e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1e7f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e800 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
1e810 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
1e820 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
1e830 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1e840 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1e850 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1e860 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
1e870 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1e880 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
1e890 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
1e8a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
1e8b0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
1e8c0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
1e8d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1e8e0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
1e8f0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
1e900 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
1e910 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
1e920 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
1e930 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
1e940 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
1e950 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
1e960 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
1e970 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
1e980 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
1e990 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1e9a0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
1e9b0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1e9c0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
1e9d0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
1e9e0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
1e9f0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
1ea00 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
1ea10 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
1ea20 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
1ea30 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
1ea40 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
1ea50 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
1ea60 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
1ea70 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1ea80 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
1ea90 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
1eaa0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
1eab0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
1eac0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
1ead0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
1eae0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1eaf0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
1eb00 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
1eb10 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
1eb20 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
1eb30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1eb40 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
1eb50 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
1eb60 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
1eb70 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
1eb80 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
1eb90 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
1eba0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
1ebb0 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
1ebc0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
1ebd0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
1ebe0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
1ebf0 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
1ec00 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
1ec10 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
1ec20 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
1ec30 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
1ec40 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
1ec50 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
1ec60 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
1ec70 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
1ec80 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
1ec90 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
1eca0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
1ecb0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
1ecc0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
1ecd0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
1ece0 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ding}.**.** ^(In
1ecf0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1ed00 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
1ed10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ed20 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
1ed30 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
1ed40 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
1ed50 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
1ed60 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
1ed70 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
1ed80 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
1ed90 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
1eda0 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
1edb0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
1edc0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
1edd0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
1ede0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
1edf0 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
1ee00 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
1ee10 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
1ee20 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
1ee30 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
1ee40 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
1ee50 20 69 64 65 6e 74 69 66 65 72 2e 29 5e 20 20 5e   identifer.)^  ^
1ee60 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
1ee70 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
1ee80 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
1ee90 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
1eea0 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
1eeb0 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
1eec0 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
1eed0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1eee0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
1eef0 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
1ef00 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
1ef10 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
1ef20 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1ef30 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a  tines is always.
1ef40 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
1ef50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1ef60 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
1ef70 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
1ef80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1ef90 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1efa0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  s..**.** ^The se
1efb0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
1efc0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1efd0 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
1efe0 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54  to be set..** ^T
1eff0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
1f000 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
1f010 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57   index of 1.  ^W
1f020 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  hen the same nam
1f030 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ed.** SQL parame
1f040 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
1f050 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
1f060 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
1f070 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
1f080 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
1f090 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
1f0a0 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a  t occurrence..**
1f0b0 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20   ^The index for 
1f0c0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
1f0d0 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
1f0e0 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
1f0f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1f100 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
1f110 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
1f120 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66   ^The index.** f
1f130 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65  or "?NNN" parame
1f140 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75  ters is the valu
1f150 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68  e of NNN..** ^Th
1f160 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
1f170 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
1f180 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
1f190 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
1f1a0 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
1f1b0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1f1c0 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
1f1d0 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
1f1e0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
1f1f0 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
1f200 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
1f210 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1f220 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
1f230 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
1f240 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
1f250 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
1f260 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1f270 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
1f280 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
1f290 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
1f2a0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
1f2b0 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
1f2c0 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
1f2d0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
1f2e0 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
1f2f0 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
1f300 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
1f310 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67  gative, the leng
1f320 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
1f330 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
1f340 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
1f350 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
1f360 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
1f370 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
1f380 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1f390 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
1f3a0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1f3b0 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
1f3c0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
1f3d0 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
1f3e0 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
1f3f0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
1f400 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
1f410 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
1f420 65 64 20 77 69 74 68 20 69 74 2e 20 5e 49 66 20  ed with it. ^If 
1f430 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
1f440 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
1f450 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
1f460 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
1f470 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
1f480 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
1f490 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
1f4a0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
1f4b0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
1f4c0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
1f4d0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
1f4e0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
1f4f0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
1f500 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
1f510 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
1f520 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
1f530 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
1f540 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
1f550 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
1f560 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1f570 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1f580 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
1f590 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
1f5a0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
1f5b0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
1f5c0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
1f5d0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
1f5e0 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
1f5f0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
1f600 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
1f610 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
1f620 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
1f630 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
1f640 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
1f650 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
1f660 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
1f670 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
1f680 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
1f690 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
1f6a0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
1f6b0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
1f6c0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
1f6d0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
1f6e0 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
1f6f0 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
1f700 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
1f710 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
1f720 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
1f730 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
1f740 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
1f750 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1f760 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
1f770 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
1f780 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
1f790 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f7a0 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
1f7b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f7c0 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
1f7d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f7e0 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
1f7f0 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
1f800 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
1f810 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
1f820 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
1f830 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
1f840 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
1f850 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
1f860 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
1f870 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1f880 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
1f890 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
1f8a0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
1f8b0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
1f8c0 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
1f8d0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
1f8e0 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
1f8f0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
1f900 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
1f910 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
1f920 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
1f930 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
1f940 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
1f950 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
1f960 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
1f970 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
1f980 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
1f990 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
1f9a0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
1f9b0 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  g..** ^[SQLITE_R
1f9c0 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
1f9d0 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
1f9e0 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
1f9f0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
1fa00 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
1fa10 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
1fa20 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
1fa30 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1fa40 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1fa50 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
1fa60 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1fa70 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
1fa80 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1fa90 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1faa0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
1fab0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1fac0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
1fad0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
1fae0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1faf0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1fb00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
1fb10 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
1fb20 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
1fb30 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1fb40 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
1fb50 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
1fb60 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1fb70 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
1fb80 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
1fb90 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
1fba0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
1fbb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1fbc0 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
1fbd0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
1fbe0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1fbf0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
1fc00 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
1fc10 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
1fc20 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
1fc30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1fc40 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1fc50 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1fc60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1fc70 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
1fc80 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1fc90 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
1fca0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
1fcb0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
1fcc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1fcd0 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
1fce0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
1fcf0 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
1fd00 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
1fd10 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
1fd20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
1fd30 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
1fd40 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
1fd50 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
1fd60 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
1fd70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
1fd80 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
1fd90 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
1fda0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
1fdb0 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
1fdc0 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
1fdd0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
1fde0 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
1fdf0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
1fe00 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
1fe10 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
1fe20 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
1fe30 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
1fe40 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
1fe50 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
1fe60 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
1fe70 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
1fe80 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
1fe90 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
1fea0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
1feb0 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
1fec0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
1fed0 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
1fee0 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
1fef0 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
1ff00 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
1ff10 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
1ff20 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
1ff30 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1ff40 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1ff50 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1ff60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1ff70 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1ff80 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1ff90 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1ffa0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
1ffb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1ffc0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1ffd0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
1ffe0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fff0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
20000 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a  t Parameter.**.*
20010 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
20020 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
20030 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
20040 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
20050 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
20060 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
20070 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
20080 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
20090 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
200a0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
200b0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
200c0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
200d0 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
200e0 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
200f0 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
20100 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
20110 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
20120 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
20130 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
20140 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
20150 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
20160 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
20170 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
20180 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
20190 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
201a0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
201b0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
201c0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
201d0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
201e0 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
201f0 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
20200 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
20210 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
20220 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
20230 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
20240 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
20250 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
20260 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
20270 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
20280 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
20290 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
202a0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
202b0 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
202c0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
202d0 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
202e0 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
202f0 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
20300 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
20310 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
20320 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
20330 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20340 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
20350 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
20360 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
20370 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
20380 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
20390 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
203a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
203b0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
203c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
203d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
203e0 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
203f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
20400 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
20410 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
20420 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
20430 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
20440 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
20450 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
20460 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
20470 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
20480 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
20490 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
204a0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
204b0 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
204c0 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
204d0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
204e0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
204f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
20500 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
20510 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
20520 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
20530 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
20540 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
20550 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
20560 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
20570 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
20580 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
20590 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
205a0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
205b0 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
205c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
205d0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
205e0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
205f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
20600 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
20610 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
20620 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
20630 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
20640 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
20650 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
20660 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
20670 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
20680 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
20690 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
206a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
206b0 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
206c0 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
206d0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
206e0 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
206f0 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
20700 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
20710 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
20720 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
20730 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
20740 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
20750 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
20760 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
20770 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
20780 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
20790 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
207a0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
207b0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
207c0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
207d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
207e0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
207f0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
20800 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
20810 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
20820 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
20830 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
20840 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
20850 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20860 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
20870 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
20880 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
20890 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
208a0 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
208b0 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
208c0 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
208d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
208e0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
208f0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
20900 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
20910 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
20920 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
20930 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
20940 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
20950 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
20960 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
20970 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
20980 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
20990 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
209a0 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
209b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
209c0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
209d0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
209e0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
209f0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
20a00 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
20a10 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
20a20 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
20a30 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
20a40 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
20a50 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
20a60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
20a70 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
20a80 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
20a90 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
20aa0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
20ab0 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
20ac0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
20ad0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
20ae0 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
20af0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
20b00 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
20b10 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
20b20 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
20b30 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
20b40 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
20b50 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
20b60 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
20b70 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
20b80 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
20b90 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
20ba0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20bb0 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
20bc0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
20bd0 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
20be0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
20bf0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20c00 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
20c10 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
20c20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
20c30 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
20c40 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
20c50 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
20c60 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
20c70 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
20c80 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
20c90 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
20ca0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
20cb0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
20cc0 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
20cd0 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
20ce0 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
20cf0 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
20d00 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
20d10 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
20d20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
20d30 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
20d40 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
20d50 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
20d60 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
20d70 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
20d80 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
20d90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
20da0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
20db0 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
20dc0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
20dd0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
20de0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
20df0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20e00 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
20e10 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
20e20 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  sult.**.** ^Thes
20e30 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
20e40 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
20e50 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
20e60 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
20e70 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
20e80 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
20e90 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
20ea0 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
20eb0 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
20ec0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
20ed0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
20ee0 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
20ef0 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
20f00 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
20f10 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
20f20 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
20f30 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
20f40 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
20f50 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
20f60 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
20f70 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
20f80 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
20f90 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
20fa0 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
20fb0 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
20fc0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
20fd0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
20fe0 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
20ff0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
21000 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
21010 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
21020 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
21030 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
21040 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
21050 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
21060 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
21070 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
21080 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
21090 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
210a0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
210b0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
210c0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
210d0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
210e0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
210f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
21100 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
21110 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
21120 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
21130 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
21140 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
21150 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
21160 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
21170 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
21180 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
21190 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
211a0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
211b0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
211c0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
211d0 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
211e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
211f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
21200 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
21210 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
21220 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
21230 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
21240 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
21250 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
21260 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
21270 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
21280 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
21290 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
212a0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
212b0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
212c0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
212d0 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
212e0 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
212f0 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
21300 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
21310 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
21320 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
21330 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
21340 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
21350 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
21360 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
21370 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
21380 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
21390 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
213a0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
213b0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
213c0 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
213d0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
213e0 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
213f0 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
21400 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
21410 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
21420 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
21430 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
21440 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
21450 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
21460 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
21470 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
21480 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
21490 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
214a0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
214b0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
214c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
214d0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
214e0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
214f0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
21500 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
21510 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
21520 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
21530 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
21540 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
21550 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
21560 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
21570 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
21580 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
21590 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
215a0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
215b0 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
215c0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
215d0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
215e0 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
215f0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
21600 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
21610 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
21620 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
21630 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
21640 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
21650 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
21660 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
21670 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
21680 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
21690 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
216a0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
216b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
216c0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
216d0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
216e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
216f0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
21700 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
21710 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
21720 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
21730 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
21740 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
21750 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21760 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
21770 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
21780 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28   Result.**.** ^(
21790 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
217a0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
217b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
217c0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
217d0 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
217e0 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
217f0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
21800 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
21810 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
21820 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
21830 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
21840 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
21850 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
21860 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
21870 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
21880 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
21890 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
218a0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
218b0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
218c0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
218d0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
218e0 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
218f0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
21900 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
21910 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
21920 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
21930 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
21940 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
21950 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
21960 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
21970 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
21980 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
21990 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
219a0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
219b0 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
219c0 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
219d0 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
219e0 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
219f0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
21a00 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
21a10 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
21a20 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
21a30 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
21a40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
21a50 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
21a60 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
21a70 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
21a80 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
21a90 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
21aa0 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
21ab0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
21ac0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
21ad0 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
21ae0 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
21af0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
21b00 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
21b10 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
21b20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
21b30 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
21b40 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
21b50 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
21b60 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
21b70 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
21b80 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
21b90 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
21ba0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
21bb0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
21bc0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
21bd0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
21be0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
21bf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
21c00 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
21c10 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
21c20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
21c30 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
21c40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
21c50 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
21c60 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
21c70 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
21c80 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
21c90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21ca0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
21cb0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
21cc0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
21cd0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
21ce0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
21cf0 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
21d00 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
21d10 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
21d20 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
21d30 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
21d40 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
21d50 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
21d60 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
21d70 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
21d80 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
21d90 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
21da0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
21db0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
21dc0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
21dd0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
21de0 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
21df0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
21e00 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
21e10 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
21e20 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
21e30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21e40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
21e50 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
21e60 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
21e70 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
21e80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
21e90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
21ea0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
21eb0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
21ec0 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
21ed0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
21ee0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
21ef0 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
21f00 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
21f10 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
21f20 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
21f30 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
21f40 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
21f50 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
21f60 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
21f70 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
21f80 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
21f90 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
21fa0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
21fb0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
21fc0 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
21fd0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
21fe0 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
21ff0 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
22000 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
22010 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
22020 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
22030 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
22040 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
22050 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
22060 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
22070 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
22080 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
22090 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
220a0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
220b0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
220c0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
220d0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
220e0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
220f0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
22100 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
22110 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
22120 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
22130 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
22140 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
22150 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
22160 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
22170 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
22180 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
22190 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
221a0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
221b0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
221c0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
221d0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
221e0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
221f0 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
22200 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
22210 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
22220 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
22230 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
22240 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
22250 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
22260 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
22270 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
22280 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
22290 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
222a0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
222b0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
222c0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
222d0 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
222e0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
222f0 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
22300 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
22310 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
22320 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
22330 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
22340 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
22350 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
22360 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
22370 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
22380 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
22390 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
223a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
223b0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
223c0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
223d0 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
223e0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
223f0 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
22400 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
22410 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
22420 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
22430 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
22440 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
22450 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
22460 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
22470 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
22480 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
22490 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
224a0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
224b0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
224c0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
224d0 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
224e0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
224f0 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
22500 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
22510 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
22520 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
22530 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
22540 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
22550 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
22560 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
22570 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
22580 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
22590 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
225a0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
225b0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
225c0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
225d0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
225e0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
225f0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
22600 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
22610 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
22620 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
22630 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
22640 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
22650 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
22660 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
22670 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
22680 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
22690 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
226a0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
226b0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
226c0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
226d0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
226e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
226f0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
22700 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
22710 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
22720 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
22730 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
22740 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
22750 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
22760 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
22770 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
22780 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
22790 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
227a0 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
227b0 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
227c0 20 69 74 20 77 61 73 20 72 65 71 75 69 72 65 64   it was required
227d0 0a 2a 2a 20 61 66 74 65 72 20 73 71 6c 69 74 65  .** after sqlite
227e0 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
227f0 64 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72  d anything other
22800 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
22810 57 5d 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  W] that.** [sqli
22820 74 65 33 5f 72 65 73 65 74 28 29 5d 20 62 65 20  te3_reset()] be 
22830 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 61 6e  called before an
22840 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
22850 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
22860 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
22870 61 69 6c 75 72 65 20 74 6f 20 69 6e 76 6f 6b 65  ailure to invoke
22880 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
22890 29 5d 20 69 6e 20 74 68 69 73 20 77 61 79 20 77  )] in this way w
228a0 6f 75 6c 64 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ould.** result i
228b0 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
228c0 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
228d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
228e0 20 20 42 75 74 20 61 66 74 65 72 0a 2a 2a 20 76    But after.** v
228f0 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
22900 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
22910 62 65 67 61 6e 20 63 61 6c 6c 69 6e 67 20 5b 73  began calling [s
22920 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
22930 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
22940 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
22950 73 74 61 6e 63 65 20 72 61 74 68 65 72 20 74 68  stance rather th
22960 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
22970 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 0a  LITE_MISUSE].  .
22980 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
22990 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
229a0 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
229b0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
229c0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
229d0 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
229e0 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
229f0 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
22a00 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
22a10 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
22a20 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
22a30 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
22a40 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
22a50 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
22a60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
22a70 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
22a80 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
22a90 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
22aa0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
22ab0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
22ac0 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
22ad0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
22ae0 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
22af0 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
22b00 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
22b10 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
22b20 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
22b30 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
22b40 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
22b50 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
22b60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
22b70 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
22b80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22b90 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
22ba0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
22bb0 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
22bc0 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
22bd0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
22be0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
22bf0 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
22c00 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
22c10 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
22c20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
22c30 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
22c40 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
22c50 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
22c60 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
22c70 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
22c80 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20  mmended..*/.int 
22c90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
22ca0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
22cb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
22cc0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
22cd0 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
22ce0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
22cf0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
22d00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
22d10 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
22d20 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
22d30 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
22d40 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2f  statement] P..*/
22d50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
22d60 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
22d70 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
22d80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
22d90 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
22da0 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
22db0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
22dc0 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
22dd0 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
22de0 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
22df0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
22e00 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
22e10 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
22e20 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
22e30 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
22e40 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
22e50 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
22e60 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
22e70 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
22e80 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
22e90 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
22ea0 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
22eb0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
22ec0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
22ed0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
22ee0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
22ef0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
22f00 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
22f10 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
22f20 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
22f30 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
22f40 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
22f50 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
22f60 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
22f70 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
22f80 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
22f90 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
22fa0 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
22fb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
22fc0 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
22fd0 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
22fe0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
22ff0 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
23000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
23010 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
23020 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
23030 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
23040 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
23050 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
23060 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
23070 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
23080 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
23090 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
230a0 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
230b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
230c0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
230d0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
230e0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
230f0 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20  he "result set" 
23100 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
23110 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
23120 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
23130 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
23140 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
23150 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
23160 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
23170 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
23180 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
23190 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
231a0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
231b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
231c0 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
231d0 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
231e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
231f0 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
23200 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
23210 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
23220 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
23230 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
23240 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
23250 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
23260 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
23270 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
23280 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
23290 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
232a0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
232b0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
232c0 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
232d0 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
232e0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
232f0 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
23300 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
23310 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
23320 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
23330 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
23340 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
23350 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
23360 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
23370 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
23380 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
23390 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
233a0 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
233b0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
233c0 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
233d0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
233e0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
233f0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
23400 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
23410 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
23420 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
23430 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
23440 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
23450 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
23460 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
23470 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
23480 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
23490 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
234a0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
234b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
234c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
234d0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
234e0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
234f0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
23500 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
23510 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
23520 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
23530 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
23540 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
23550 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
23560 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
23570 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
23580 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
23590 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
235a0 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
235b0 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
235c0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
235d0 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
235e0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
235f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
23600 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
23610 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
23620 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
23630 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
23640 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
23650 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
23660 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
23670 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
23680 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
23690 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
236a0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
236b0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
236c0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
236d0 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
236e0 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
236f0 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
23700 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
23710 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
23720 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
23730 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
23740 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
23750 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
23760 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
23770 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
23780 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
23790 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
237a0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
237b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
237c0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
237d0 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
237e0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
237f0 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
23800 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
23810 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
23820 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
23830 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
23840 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
23850 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
23860 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
23870 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
23880 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
23890 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
238a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
238b0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
238c0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
238d0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
238e0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
238f0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
23900 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
23910 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
23920 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
23930 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
23940 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
23950 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
23960 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
23970 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
23980 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
23990 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
239a0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
239b0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
239c0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
239d0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
239e0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
239f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
23a00 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
23a10 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
23a20 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
23a30 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
23a40 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20  rminator at the 
23a50 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
23a60 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
23a70 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72  ity: the value r
23a80 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e  eturned is the n
23a90 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
23aa0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
23ab0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
23ac0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
23ad0 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
23ae0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
23af0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
23b00 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
23b10 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
23b20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
23b30 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
23b40 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
23b50 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
23b60 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
23b70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
23b80 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
23b90 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72  th BLOB is an ar
23ba0 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74  bitrary.** point
23bb0 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65  er, possibly eve
23bc0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
23bd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
23be0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23bf0 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73  s16() routine is
23c00 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69   similar to sqli
23c10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
23c20 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73  ().** but leaves
23c30 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55   the result in U
23c40 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20  TF-16 in native 
23c50 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65  byte order inste
23c60 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20  ad of UTF-8..** 
23c70 5e 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ^The zero termin
23c80 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c  ator is not incl
23c90 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75  uded in this cou
23ca0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  nt..**.** ^The o
23cb0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
23cc0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
23cd0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
23ce0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
23cf0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
23d00 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
23d10 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23d20 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
23d30 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
23d40 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
23d50 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
23d60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
23d70 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
23d80 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
23d90 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
23da0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
23db0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
23dc0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
23dd0 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
23de0 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
23df0 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
23e00 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
23e10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
23e20 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
23e30 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
23e40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
23e50 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
23e60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
23e70 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
23e80 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
23e90 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
23ea0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
23eb0 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
23ec0 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
23ed0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
23ee0 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
23ef0 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
23f00 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
23f10 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
23f20 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
23f30 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
23f40 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
23f50 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
23f60 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
23f70 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
23f80 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
23f90 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
23fa0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
23fb0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
23fc0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
23fd0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
23fe0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
23ff0 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
24000 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
24010 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
24020 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
24030 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
24040 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
24050 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
24060 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
24070 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
24080 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
24090 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
240a0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
240b0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
240c0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
240d0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
240e0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
240f0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
24100 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
24110 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
24120 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
24130 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
24140 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
24150 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
24160 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
24170 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
24180 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
24190 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
241a0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
241b0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
241c0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
241d0 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
241e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
241f0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
24200 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
24210 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20  t from float to 
24220 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
24230 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
24240 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
24250 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
24260 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
24270 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
24280 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
24290 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46    <td> Same as F
242a0 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  LOAT->TEXT.** <t
242b0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
242c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
242d0 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a  td> Use atoi().*
242e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
242f0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
24300 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66     <td> Use atof
24310 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
24320 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
24330 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
24340 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
24350 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
24360 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
24370 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
24380 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a  hen use atoi().*
24390 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
243a0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
243b0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
243c0 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
243d0 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
243e0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
243f0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
24400 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
24410 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
24420 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
24430 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
24440 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
24450 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
24460 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
24470 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
24480 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
24490 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
244a0 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
244b0 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
244c0 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
244d0 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
244e0 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
244f0 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
24500 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
24510 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
24520 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
24530 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
24540 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
24550 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
24560 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
24570 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  rs..**.** ^Note 
24580 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
24590 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
245a0 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
245b0 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
245c0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
245d0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
245e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
245f0 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
24600 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24610 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
24620 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
24630 5e 28 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  ^(Type conversio
24640 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
24650 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
24660 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
24670 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
24680 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
24690 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
246a0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
246b0 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
246c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
246d0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
246e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
246f0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
24700 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
24710 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
24720 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
24730 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
24740 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
24750 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
24760 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
24770 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24780 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
24790 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
247a0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
247b0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
247c0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
247d0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
247e0 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
247f0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
24800 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
24810 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
24820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24830 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
24840 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24850 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
24860 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
24870 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
24880 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
24890 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29  .</li>.** </ul>)
248a0 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  ^.**.** ^Convers
248b0 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
248c0 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
248d0 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
248e0 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
248f0 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
24900 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
24910 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
24920 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
24930 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
24940 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
24950 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74  or pointer point
24960 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62  s to will have b
24970 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
24980 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
24990 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
249a0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
249b0 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
249c0 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
249d0 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
249e0 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
249f0 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
24a00 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
24a10 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
24a20 2a 2a 20 5e 28 54 68 65 20 73 61 66 65 73 74 20  ** ^(The safest 
24a30 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
24a40 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
24a50 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
24a60 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
24a70 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
24a80 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
24a90 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
24aa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24ab0 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
24ac0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24ad0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
24ae0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
24af0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
24b00 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
24b10 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
24b20 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
24b30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
24b40 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
24b50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24b60 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
24b70 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e  </ul>)^.**.** In
24b80 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
24b90 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
24ba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24bb0 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
24bc0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
24bd0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
24be0 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
24bf0 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
24c00 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
24c10 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
24c20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
24c30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24c40 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
24c50 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
24c60 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
24c70 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
24c80 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
24c90 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
24ca0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
24cb0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
24cc0 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
24cd0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
24ce0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
24cf0 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
24d00 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
24d10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
24d20 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
24d30 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
24d40 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
24d50 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
24d60 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
24d70 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
24d80 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
24d90 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
24da0 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
24db0 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
24dc0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
24dd0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
24de0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
24df0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
24e00 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
24e10 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
24e20 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
24e30 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
24e40 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
24e50 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
24e60 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
24e70 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
24e80 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
24e90 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
24ea0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
24eb0 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
24ec0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
24ed0 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
24ee0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
24ef0 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
24f00 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
24f10 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
24f20 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
24f30 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
24f40 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
24f50 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
24f60 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
24f70 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
24f80 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
24f90 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
24fa0 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
24fb0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
24fc0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
24fd0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
24fe0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
24ff0 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  .)^.*/.const voi
25000 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
25010 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
25020 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
25030 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
25040 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
25050 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
25060 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
25070 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
25080 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25090 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
250a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
250b0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
250c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
250d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
250e0 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
250f0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
25100 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
25110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
25120 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
25130 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
25140 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
25150 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
25160 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
25170 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
25180 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
25190 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
251a0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
251b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
251c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
251d0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
251e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
251f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
25200 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
25210 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
25220 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
25230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
25240 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
25250 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
25260 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
25270 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
25280 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
25290 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
252a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
252b0 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
252c0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78  statement was ex
252d0 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75  ecuted successfu
252e0 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75  lly or not execu
252f0 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e  ted at all, then
25300 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  .** SQLITE_OK is
25310 20 72 65 74 75 72 6e 65 64 2e 20 5e 49 66 20 65   returned. ^If e
25320 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
25330 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64  statement failed
25340 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72   then an.** [err
25350 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  or code] or [ext
25360 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
25370 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
25380 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
25390 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
253a0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
253b0 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ring the executi
253c0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72  on of the.** [pr
253d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
253e0 5d 2e 20 20 5e 49 66 20 74 68 65 20 76 69 72 74  ].  ^If the virt
253f0 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20  ual machine has 
25400 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  not.** completed
25410 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20   execution when 
25420 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
25430 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20  called, that is 
25440 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  like.** encounte
25450 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72  ring an error or
25460 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   an [sqlite3_int
25470 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75  errupt | interru
25480 70 74 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f 6d 70 6c  pt]..** ^Incompl
25490 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20  ete updates may 
254a0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
254b0 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  nd transactions 
254c0 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70  canceled,.** dep
254d0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69  ending on the ci
254e0 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64  rcumstances, and
254f0 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63   the.** [error c
25500 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69  ode] returned wi
25510 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42  ll be [SQLITE_AB
25520 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ORT]..*/.int sql
25530 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
25540 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
25550 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
25560 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
25570 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
25580 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
25590 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
255a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
255b0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
255c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
255d0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
255e0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
255f0 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
25600 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
25610 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
25620 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
25630 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
25640 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
25650 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
25660 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
25670 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
25680 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
25690 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
256a0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
256b0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
256c0 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
256d0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
256e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
256f0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
25700 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
25710 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
25720 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
25730 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
25740 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
25750 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
25760 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
25770 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
25780 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
25790 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
257a0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
257b0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
257c0 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
257d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
257e0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
257f0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
25800 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
25810 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
25820 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
25830 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
25840 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
25850 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
25860 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
25870 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
25880 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
25890 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
258a0 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
258b0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
258c0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
258d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
258e0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
258f0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
25900 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
25910 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
25920 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
25930 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
25940 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
25950 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25960 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
25970 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
25980 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
25990 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
259a0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
259b0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
259c0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
259d0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
259e0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
259f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
25a00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25a10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
25a20 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
25a30 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25a40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
25a50 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 74 77 6f  **.** ^These two
25a60 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
25a70 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
25a80 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
25a90 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
25aa0 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
25ab0 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
25ac0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
25ad0 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
25ae0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
25af0 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
25b00 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
25b10 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
25b20 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77   difference betw
25b30 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69  een the.** two i
25b40 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
25b50 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  d parameter, the
25b60 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63   name of the (sc
25b70 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f  alar) function o
25b80 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20  r.** aggregate, 
25b90 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  is encoded in UT
25ba0 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  F-8 for sqlite3_
25bb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
25bc0 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20  ) and UTF-16.** 
25bd0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
25be0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e  te_function16().
25bf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
25c00 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
25c10 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
25c20 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
25c30 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
25c40 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
25c50 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
25c60 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
25c70 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
25c80 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
25c90 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
25ca0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
25cb0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
25cc0 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
25cd0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
25ce0 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
25cf0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ly..**.** The se
25d00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
25d10 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
25d20 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
25d30 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
25d40 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
25d50 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
25d60 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
25d70 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20  d to 255 bytes, 
25d80 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20  exclusive of.** 
25d90 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
25da0 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  tor.  Note that 
25db0 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20  the name length 
25dc0 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65  limit is in byte
25dd0 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63  s, not.** charac
25de0 74 65 72 73 2e 20 20 5e 41 6e 79 20 61 74 74 65  ters.  ^Any atte
25df0 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
25e00 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
25e10 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
25e20 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
25e30 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69  QLITE_ERROR] bei
25e40 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
25e50 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
25e60 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
25e70 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
25e80 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
25e90 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
25ea0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
25eb0 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
25ec0 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
25ed0 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
25ee0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
25ef0 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
25f00 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
25f10 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
25f20 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
25f30 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
25f40 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
25f50 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
25f60 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
25f70 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
25f80 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
25f90 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
25fa0 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
25fb0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
25fc0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
25fd0 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
25fe0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
25ff0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
26000 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
26010 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
26020 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
26030 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
26040 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
26050 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e  rs.  Any SQL fun
26060 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
26070 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61  tion should be a
26080 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
26090 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20  ork with UTF-8, 
260a0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
260b0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
260c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
260d0 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
260e0 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
260f0 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
26100 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
26110 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
26120 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
26130 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26140 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
26150 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
26160 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
26170 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
26180 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
26190 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
261a0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
261b0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
261c0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
261d0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
261e0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
261f0 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
26200 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
26210 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
26220 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
26230 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
26240 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
26250 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
26260 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
26270 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
26280 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
26290 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
262a0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
262b0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
262c0 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
262d0 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
262e0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
262f0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
26300 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
26310 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
26320 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
26330 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
26340 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
26350 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
26360 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
26370 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65  ^.**.** The seve
26380 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20  nth, eighth and 
26390 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73  ninth parameters
263a0 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
263b0 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
263c0 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
263d0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
263e0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
263f0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
26400 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
26410 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
26420 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
26430 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
26440 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
26450 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
26460 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
26470 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  rs should be pas
26480 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
26490 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
264a0 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
264b0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
264c0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
264d0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
264e0 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
264f0 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
26500 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
26510 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
26520 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
26530 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
26540 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
26550 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20  , pass NULL for 
26560 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
26570 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  on callbacks..**
26580 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
26590 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
265a0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
265b0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
265c0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
265d0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
265e0 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
265f0 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
26600 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
26610 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
26620 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
26630 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
26640 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
26650 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
26660 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
26670 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
26680 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
26690 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
266a0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
266b0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
266c0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
266d0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
266e0 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
266f0 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
26700 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
26710 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
26720 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
26730 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
26740 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
26750 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
26760 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
26770 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
26780 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
26790 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
267a0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
267b0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
267c0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
267d0 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
267e0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
267f0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
26800 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
26810 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
26820 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
26830 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
26840 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
26850 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
26860 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
26870 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
26880 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
26890 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
268a0 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
268b0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
268c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
268d0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
268e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
268f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  ned function wit
26900 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f  h a given name o
26910 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20  verrides all.** 
26920 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  built-in functio
26930 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b  ns in the same [
26940 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26950 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61  ion] with the sa
26960 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53 75 62  me name..** ^Sub
26970 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74  sequent applicat
26980 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
26990 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
269a0 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72  e name only over
269b0 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61  ride .** prior a
269c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
269d0 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ed functions tha
269e0 74 20 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d  t are an exact m
269f0 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20  atch for the.** 
26a00 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
26a10 74 65 72 73 20 61 6e 64 20 70 72 65 66 65 72 72  ters and preferr
26a20 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  ed encoding..**.
26a30 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
26a40 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
26a50 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
26a60 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
26a70 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
26a80 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
26a90 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
26aa0 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
26ab0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26ac0 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
26ad0 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
26ae0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
26af0 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
26b00 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
26b10 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
26b20 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26b30 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
26b40 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
26b50 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
26b60 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
26b70 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
26b80 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
26b90 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
26ba0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
26bb0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
26bc0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
26bd0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
26be0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
26bf0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
26c00 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
26c10 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
26c20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
26c30 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
26c40 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
26c50 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
26c60 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
26c70 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
26c80 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
26c90 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
26ca0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
26cb0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
26cc0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
26cd0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
26ce0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
26cf0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
26d00 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
26d10 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
26d20 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ext*).);../*.** 
26d30 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
26d40 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
26d50 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
26d60 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
26d70 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
26d80 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
26d90 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
26da0 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
26db0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
26dc0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
26dd0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
26de0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
26df0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
26e00 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
26e10 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
26e20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
26e30 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
26e40 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
26e50 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
26e60 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
26e70 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
26e80 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26e90 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
26ea0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
26eb0 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
26ec0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
26ed0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
26ee0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
26ef0 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
26f00 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
26f10 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
26f20 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
26f30 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
26f40 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
26f50 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
26f60 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
26f70 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
26f80 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
26f90 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
26fa0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
26fb0 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
26fc0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
26fd0 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
26fe0 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
26ff0 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
27000 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
27010 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
27020 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
27030 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
27040 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
27050 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
27060 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
27070 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
27080 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
27090 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
270a0 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
270b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
270c0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
270d0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
270e0 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
270f0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
27100 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
27110 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
27120 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
27130 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
27140 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
27150 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
27160 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
27170 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
27180 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
27190 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
271a0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
271b0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
271c0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
271d0 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
271e0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
271f0 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
27200 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
27210 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
27220 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
27230 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
27240 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
27250 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  s.**.** The C-la
27260 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
27270 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
27280 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
27290 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
272a0 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
272b0 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
272c0 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
272d0 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
272e0 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
272f0 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
27300 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
27310 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
27320 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
27330 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
27340 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
27350 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27360 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
27370 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27380 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
27390 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
273a0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
273b0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
273c0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
273d0 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72  ..** The 4th par
273e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
273f0 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
27400 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
27410 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
27420 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27430 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
27440 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
27450 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
27460 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
27470 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
27480 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
27490 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
274a0 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
274b0 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
274c0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
274d0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
274e0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
274f0 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
27500 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27510 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
27520 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
27530 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
27540 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
27550 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27560 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
27570 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
27580 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
27590 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
275a0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
275b0 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
275c0 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
275d0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
275e0 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
275f0 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
27600 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
27610 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
27620 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
27630 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
27640 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
27650 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
27660 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
27670 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
27680 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
27690 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
276a0 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
276b0 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
276c0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
276d0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
276e0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
276f0 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
27700 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
27710 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
27720 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
27730 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
27740 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
27750 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
27760 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
27770 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
27780 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
27790 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
277a0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
277b0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
277c0 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
277d0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
277e0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
277f0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
27800 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
27810 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
27820 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
27830 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
27840 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
27850 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
27860 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
27870 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
27880 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
27890 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
278a0 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
278b0 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
278c0 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
278d0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
278e0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
278f0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
27900 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
27910 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
27920 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
27930 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
27940 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
27950 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
27960 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
27970 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
27980 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
27990 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
279a0 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
279b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
279c0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
279d0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
279e0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
279f0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
27a00 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
27a10 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
27a20 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
27a30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
27a40 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
27a50 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
27a60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
27a70 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
27a80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27a90 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
27aa0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
27ab0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
27ac0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
27ad0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
27ae0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
27af0 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
27b00 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
27b10 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
27b20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
27b30 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
27b40 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
27b50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
27b60 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
27b70 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
27b80 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
27b90 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
27ba0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
27bb0 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
27bc0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
27bd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
27be0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
27bf0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
27c00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
27c10 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
27c20 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
27c30 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
27c40 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
27c50 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
27c60 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
27c70 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
27c80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27c90 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
27ca0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
27cb0 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
27cc0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
27cd0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
27ce0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
27cf0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
27d00 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
27d10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27d20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
27d30 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
27d40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27d50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27d60 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
27d70 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
27d80 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
27d90 65 6e 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  entions of aggre
27da0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
27db0 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
27dc0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
27dd0 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
27de0 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
27df0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
27e00 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
27e10 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
27e20 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
27e30 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
27e40 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
27e50 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
27e60 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
27e70 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
27e80 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
27e90 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
27ea0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
27eb0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
27ec0 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
27ed0 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
27ee0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
27ef0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
27f00 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
27f10 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
27f20 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
27f30 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
27f40 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
27f50 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
27f60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27f70 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
27f80 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
27f90 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
27fa0 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
27fb0 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
27fc0 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
27fd0 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
27fe0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
27ff0 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
28000 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
28010 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
28020 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
28030 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
28040 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
28050 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
28060 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
28070 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
28080 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
28090 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
280a0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
280b0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
280c0 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
280d0 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
280e0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
280f0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
28100 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
28110 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
28120 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
28130 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
28140 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
28150 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73  r if N is.** les
28160 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
28170 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
28180 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20  memory allocate 
28190 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
281a0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
281b0 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
281c0 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
281d0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
281e0 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
281f0 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
28200 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
28210 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
28220 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
28230 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
28240 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
28250 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
28260 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
28270 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
28280 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
28290 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
282a0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
282b0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
282c0 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a  llocation.)^.**.
282d0 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
282e0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
282f0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
28300 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
28310 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
28320 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
28330 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
28340 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
28350 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
28360 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
28370 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
28380 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
28390 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
283a0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
283b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
283c0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
283d0 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
283e0 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
283f0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
28400 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
28410 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
28420 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
28430 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
28440 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
28450 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
28460 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
28470 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
28480 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
28490 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
284a0 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
284b0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
284c0 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
284d0 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
284e0 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
284f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28500 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
28510 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
28520 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
28530 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
28540 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
28550 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
28560 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
28570 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
28580 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
28590 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
285a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
285b0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
285c0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
285d0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
285e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
285f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
28600 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
28610 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
28620 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
28630 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
28640 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
28650 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
28660 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
28670 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
28680 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
28690 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
286a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
286b0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
286c0 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
286d0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
286e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
286f0 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
28700 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
28710 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
28720 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
28730 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
28740 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
28750 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
28760 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
28770 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
28780 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
28790 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
287a0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
287b0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
287c0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
287d0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
287e0 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69  unction..*/.sqli
287f0 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
28800 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
28810 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
28820 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28830 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
28840 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
28850 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
28860 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
28870 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
28880 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
28890 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
288a0 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
288b0 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
288c0 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
288d0 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
288e0 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
288f0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
28900 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
28910 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
28920 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
28930 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
28940 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
28950 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
28960 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
28970 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
28980 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
28990 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
289a0 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
289b0 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
289c0 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
289d0 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
289e0 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
289f0 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
28a00 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
28a10 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
28a20 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
28a30 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
28a40 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
28a50 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
28a60 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
28a70 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
28a80 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
28a90 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
28aa0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
28ab0 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
28ac0 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
28ad0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
28ae0 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
28af0 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
28b00 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
28b10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
28b20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
28b30 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
28b40 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
28b50 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
28b60 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
28b70 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
28b80 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
28b90 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
28ba0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
28bb0 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
28bc0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28bd0 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f  function. ^If no
28be0 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
28bf0 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20  en ever.** been 
28c00 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20  set for the Nth 
28c10 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
28c20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
28c30 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
28c40 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  g.** function pa
28c50 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e  rameter has chan
28c60 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
28c70 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
28c80 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
28c90 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72  _get_auxdata() r
28ca0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
28cb0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
28cc0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
28cd0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
28ce0 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
28cf0 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
28d00 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
28d10 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
28d20 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
28d30 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
28d40 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
28d50 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
28d60 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e  tion.  Subsequen
28d70 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
28d80 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
28d90 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e  a() might return
28da0 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69   this data, if i
28db0 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65  t has.** not bee
28dc0 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20  n destroyed..** 
28dd0 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  ^If it is not NU
28de0 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
28df0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
28e00 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
28e10 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
28e20 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
28e30 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
28e40 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
28e50 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
28e60 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
28e70 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
28e80 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
28e90 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
28ea0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
28eb0 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
28ec0 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
28ed0 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
28ee0 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
28ef0 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
28f00 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
28f10 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
28f20 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
28f30 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f  ny time.  ^The o
28f40 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73  nly guarantee is
28f50 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73   that.** the des
28f60 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
28f70 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
28f80 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72  e metadata is dr
28f90 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  opped..**.** ^(I
28fa0 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
28fb0 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
28fc0 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
28fd0 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
28fe0 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
28ff0 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
29000 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
29010 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
29020 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
29030 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e  nd [parameters].
29040 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
29050 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
29060 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
29070 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
29080 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
29090 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
290a0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
290b0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
290c0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
290d0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
290e0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
290f0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
29100 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
29110 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
29120 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
29130 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
29140 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
29150 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
29160 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
29170 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
29180 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
29190 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
291a0 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
291b0 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
291c0 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
291d0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
291e0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
291f0 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
29200 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
29210 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
29220 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
29230 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
29240 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
29250 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
29260 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
29270 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
29280 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
29290 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
292a0 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
292b0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
292c0 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
292d0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
292e0 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
292f0 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
29300 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
29310 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
29320 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
29330 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
29340 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
29350 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
29360 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
29370 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
29380 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
29390 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
293a0 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
293b0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
293c0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
293d0 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
293e0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
293f0 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
29400 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
29410 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
29420 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
29430 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
29440 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
29450 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
29460 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
29470 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
29480 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
29490 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
294a0 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
294b0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
294c0 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
294d0 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
294e0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
294f0 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
29500 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
29510 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
29520 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
29530 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
29540 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
29550 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
29560 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
29570 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
29580 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
29590 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
295a0 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
295b0 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
295c0 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
295d0 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
295e0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
295f0 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
29600 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
29610 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
29620 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
29630 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
29640 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
29650 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
29660 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
29670 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
29680 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29690 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
296a0 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
296b0 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
296c0 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
296d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
296e0 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
296f0 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
29700 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
29710 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
29720 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29730 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
29740 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
29750 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
29760 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
29770 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
29780 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
29790 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
297a0 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
297b0 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
297c0 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
297d0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
297e0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
297f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29800 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
29810 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
29820 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
29830 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
29840 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
29850 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
29860 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
29870 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
29880 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
29890 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
298a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
298b0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
298c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
298d0 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
298e0 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
298f0 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
29900 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
29910 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
29920 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
29930 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
29940 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
29950 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
29960 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
29970 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
29980 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
29990 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
299a0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
299b0 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
299c0 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
299d0 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
299e0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
299f0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
29a00 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
29a10 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
29a20 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
29a30 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29a40 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
29a50 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
29a60 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
29a70 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
29a80 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
29a90 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
29aa0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
29ab0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
29ac0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
29ad0 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
29ae0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
29af0 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
29b00 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
29b10 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
29b20 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
29b30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
29b40 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29b50 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
29b60 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
29b70 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
29b80 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
29b90 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
29ba0 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
29bb0 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
29bc0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
29bd0 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
29be0 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
29bf0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29c00 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
29c10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
29c20 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
29c30 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
29c40 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
29c50 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
29c60 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
29c70 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
29c80 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
29c90 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
29ca0 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
29cb0 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
29cc0 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
29cd0 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
29ce0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29cf0 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
29d00 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
29d10 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
29d20 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
29d30 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
29d40 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
29d50 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
29d60 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
29d70 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
29d80 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
29d90 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
29da0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29db0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
29dc0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
29dd0 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
29de0 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
29df0 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
29e00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
29e10 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e  sult_toobig() in
29e20 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
29e30 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
29e40 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
29e50 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
29e60 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
29e70 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
29e80 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
29e90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29ea0 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
29eb0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
29ec0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
29ed0 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
29ee0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
29ef0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
29f00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29f10 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
29f20 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
29f30 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
29f40 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
29f50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
29f60 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
29f70 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
29f80 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
29f90 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
29fa0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
29fb0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
29fc0 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
29fd0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
29fe0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
29ff0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2a000 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2a010 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
2a020 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2a030 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
2a040 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
2a050 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
2a060 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a070 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
2a080 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
2a090 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
2a0a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2a0b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2a0c0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2a0d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2a0e0 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
2a0f0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2a100 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
2a110 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2a120 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
2a130 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
2a140 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
2a150 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
2a160 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
2a170 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2a180 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
2a190 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
2a1a0 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
2a1b0 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
2a1c0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
2a1d0 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
2a1e0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
2a1f0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
2a200 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
2a210 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ely..** ^SQLite 
2a220 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
2a230 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
2a240 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
2a250 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
2a260 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
2a270 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2a280 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
2a290 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
2a2a0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2a2b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a2c0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2a2d0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2a2e0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
2a2f0 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
2a300 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2a310 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
2a320 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
2a330 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
2a340 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2a350 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2a360 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2a370 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
2a380 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
2a390 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
2a3a0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
2a3b0 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
2a3c0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
2a3d0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
2a3e0 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
2a3f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a400 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
2a410 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
2a420 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2a430 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2a440 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2a450 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
2a460 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2a470 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
2a480 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
2a490 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
2a4a0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
2a4b0 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
2a4c0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
2a4d0 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
2a4e0 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
2a4f0 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
2a500 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
2a510 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2a520 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2a530 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2a540 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
2a550 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2a560 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
2a570 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
2a580 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
2a590 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
2a5a0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
2a5b0 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
2a5c0 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
2a5d0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
2a5e0 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
2a5f0 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
2a600 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
2a610 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
2a620 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
2a630 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
2a640 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
2a650 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
2a660 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2a670 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2a680 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2a690 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2a6a0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
2a6b0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
2a6c0 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
2a6d0 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
2a6e0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
2a6f0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
2a700 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
2a710 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
2a720 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2a730 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
2a740 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
2a750 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a760 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
2a770 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2a780 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
2a790 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2a7a0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
2a7b0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
2a7c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2a7d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2a7e0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2a7f0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
2a800 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
2a810 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2a820 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
2a830 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
2a840 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
2a850 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
2a860 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
2a870 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
2a880 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
2a890 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
2a8a0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
2a8b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2a8c0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
2a8d0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
2a8e0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2a8f0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2a900 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
2a910 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
2a920 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2a930 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2a940 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
2a950 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
2a960 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
2a970 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
2a980 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
2a990 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
2a9a0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
2a9b0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2a9c0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
2a9d0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
2a9e0 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
2a9f0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2aa00 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2aa10 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
2aa20 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
2aa30 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
2aa40 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
2aa50 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2aa60 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
2aa70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2aa80 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
2aa90 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2aaa0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
2aab0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2aac0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
2aad0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
2aae0 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
2aaf0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2ab00 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
2ab10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2ab20 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
2ab30 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2ab40 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
2ab50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2ab60 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
2ab70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2ab80 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
2ab90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2aba0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
2abb0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
2abc0 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
2abd0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
2abe0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2abf0 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
2ac00 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
2ac10 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2ac20 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
2ac30 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
2ac40 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2ac50 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
2ac60 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
2ac70 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
2ac80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
2ac90 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
2aca0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2acb0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
2acc0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2acd0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
2ace0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2acf0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2ad00 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
2ad10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2ad20 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2ad30 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2ad40 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2ad50 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
2ad60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2ad70 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2ad80 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2ad90 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2ada0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
2adb0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2adc0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2add0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
2ade0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2adf0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2ae00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ae10 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
2ae20 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2ae30 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
2ae40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ae50 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
2ae60 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
2ae70 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
2ae80 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
2ae90 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2aea0 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
2aeb0 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
2aec0 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a  quences to the.*
2aed0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
2aee0 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
2aef0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
2af00 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
2af10 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2af20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
2af30 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66  quence is specif
2af40 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73  ied as a UTF-8 s
2af50 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
2af60 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2af70 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
2af80 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2af90 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
2afa0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2afb0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
2afc0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
2afd0 29 2e 20 5e 49 6e 20 61 6c 6c 20 63 61 73 65 73  ). ^In all cases
2afe0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20  .** the name is 
2aff0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
2b000 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2b010 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2b020 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2b030 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  t may be one of 
2b040 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
2b050 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
2b060 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
2b070 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2b080 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16BE], indicatin
2b090 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d  g that the user-
2b0a0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74  supplied.** rout
2b0b0 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62  ine expects to b
2b0c0 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72  e passed pointer
2b0d0 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63  s to strings enc
2b0e0 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
2b0f0 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
2b100 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le-endian, or UT
2b110 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c  F-16 big-endian,
2b120 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 5e   respectively. ^
2b130 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67  The.** third arg
2b140 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f  ument might also
2b150 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
2b160 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  6] to indicate t
2b170 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a  hat the routine.
2b180 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ** expects point
2b190 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36  ers to be UTF-16
2b1a0 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
2b1b0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2b1c0 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67  r, or the.** arg
2b1d0 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51  ument can be [SQ
2b1e0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
2b1f0 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68  ED] if the.** th
2b200 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  e routine expect
2b210 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36  s pointers to 16
2b220 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65  -bit word aligne
2b230 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20  d strings.** of 
2b240 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
2b250 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
2b260 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
2b270 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70   to the user sup
2b280 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75  plied routine mu
2b290 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
2b2a0 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67  the fifth.** arg
2b2b0 75 6d 65 6e 74 2e 20 20 5e 49 66 20 69 74 20 69  ument.  ^If it i
2b2c0 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20  s NULL, this is 
2b2d0 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65  the same as dele
2b2e0 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69  ting the collati
2b2f0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28  on.** sequence (
2b300 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  so that SQLite c
2b310 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e  annot call it an
2b320 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61 63 68  ymore)..** ^Each
2b330 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63   time the applic
2b340 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66  ation supplied f
2b350 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
2b360 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64  ed, it is passed
2b370 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74  .** as its first
2b380 20 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70   parameter a cop
2b390 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
2b3a0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
2b3b0 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
2b3c0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
2b3d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72  e_collation() or
2b3e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b3f0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
2b400 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 6d 61 69 6e  *.** ^The remain
2b410 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ing arguments to
2b420 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b430 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e  -supplied routin
2b440 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67  e are two string
2b450 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65  s,.** each repre
2b460 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e  sented by a (len
2b470 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20  gth, data) pair 
2b480 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74  and encoded in t
2b490 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74  he encoding.** t
2b4a0 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61  hat was passed a
2b4b0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
2b4c0 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f  ment when the co
2b4d0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2b4e0 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72   was.** register
2b4f0 65 64 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  ed.  The applica
2b500 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c  tion defined col
2b510 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73  lation routine s
2b520 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
2b530 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f  negative, zero o
2b540 72 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 68  r positive if th
2b550 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
2b560 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20  s less than,.** 
2b570 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
2b580 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
2b590 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65  cond string. i.e
2b5a0 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52  . (STRING1 - STR
2b5b0 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ING2)..**.** ^Th
2b5c0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2b5d0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
2b5e0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
2b5f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2b600 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  ion().** except 
2b610 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e  that it takes an
2b620 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20   extra argument 
2b630 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72  which is a destr
2b640 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65  uctor for.** the
2b650 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e 54 68   collation.  ^Th
2b660 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2b670 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
2b680 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  collation is.** 
2b690 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73  destroyed and is
2b6a0 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f   passed a copy o
2b6b0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2b6c0 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69  ameter void* poi
2b6d0 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73  nter.** of the s
2b6e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2b6f0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  llation_v2()..**
2b700 20 5e 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65   ^Collations are
2b710 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20   destroyed when 
2b720 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
2b730 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c  den by later cal
2b740 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c  ls to the.** col
2b750 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
2b760 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
2b770 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
2b780 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
2b790 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  losed.** using [
2b7a0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2b7b0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2b7c0 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
2b7d0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
2b7e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
2b7f0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2b800 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2b810 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2b820 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
2b830 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
2b840 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
2b850 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
2b860 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
2b870 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
2b880 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
2b890 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  st void*).);.int
2b8a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b8b0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20  collation_v2(.  
2b8c0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
2b8d0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
2b8e0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2b8f0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
2b900 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
2b910 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2b920 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2b930 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
2b940 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
2b950 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2b960 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
2b970 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
2b980 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65  onst void *zName
2b990 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2b9a0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
2b9b0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
2b9c0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2b9d0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2b9e0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
2b9f0 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
2ba00 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
2ba10 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f  ks.**.** ^To avo
2ba20 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
2ba30 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
2ba40 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
2ba50 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
2ba60 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
2ba70 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
2ba80 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
2ba90 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
2baa0 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  h the.** [databa
2bab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
2bac0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
2bad0 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
2bae0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  ed collation.** 
2baf0 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75  sequence is requ
2bb00 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ired..**.** ^If 
2bb10 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
2bb20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
2bb30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2bb40 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
2bb50 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
2bb60 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
2bb70 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
2bb80 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2bb90 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
2bba0 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
2bbb0 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  F-8. ^If sqlite3
2bbc0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2bbd0 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
2bbe0 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
2bbf0 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
2bc00 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
2bc10 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
2bc20 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  * ^A call to eit
2bc30 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70  her function rep
2bc40 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69  laces the existi
2bc50 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65  ng collation-nee
2bc60 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ded callback..**
2bc70 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63  .** ^(When the c
2bc80 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
2bc90 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
2bca0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
2bcb0 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
2bcc0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2bcd0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
2bce0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
2bcf0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2bd00 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
2bd10 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
2bd20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2bd30 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2bd40 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
2bd50 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
2bd60 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
2bd70 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
2bd80 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
2bd90 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
2bda0 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
2bdb0 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
2bdc0 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
2bdd0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
2bde0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
2bdf0 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
2be00 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2be10 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
2be20 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
2be30 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a   sequence.)^.**.
2be40 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
2be50 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
2be60 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
2be70 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
2be80 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2be90 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2bea0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
2beb0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2bec0 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
2bed0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2bee0 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ation_v2()]..*/.
2bef0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
2bf00 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
2bf10 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
2bf20 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
2bf30 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
2bf40 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
2bf50 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
2bf60 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2bf70 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
2bf80 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
2bf90 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
2bfa0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
2bfb0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
2bfc0 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53  d*).);..#ifdef S
2bfd0 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a  QLITE_HAS_CODEC.
2bfe0 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
2bff0 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
2c000 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
2c010 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
2c020 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
2c030 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
2c040 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
2c050 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
2c060 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
2c070 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
2c080 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
2c090 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
2c0a0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
2c0b0 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
2c0c0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2c0d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2c0e0 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
2c0f0 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
2c100 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
2c110 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
2c120 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
2c130 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
2c140 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
2c150 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
2c160 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
2c170 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
2c180 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
2c190 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
2c1a0 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
2c1b0 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
2c1c0 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
2c1d0 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
2c1e0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
2c1f0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
2c200 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
2c210 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
2c220 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
2c230 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
2c240 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69  e3_rekey(.  sqli
2c250 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2c260 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2c270 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
2c280 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
2c290 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
2c2a0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
2c2b0 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  new key */.);../
2c2c0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
2c2d0 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
2c2e0 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61  for a SEE databa
2c2f0 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20  se.  Unless .** 
2c300 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20  activated, none 
2c310 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69  of the SEE routi
2c320 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
2c330 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  /.void sqlite3_a
2c340 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63  ctivate_see(.  c
2c350 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
2c360 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
2c370 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
2c380 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
2c390 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45  .#ifdef SQLITE_E
2c3a0 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a  NABLE_CEROD./*.*
2c3b0 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
2c3c0 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
2c3d0 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73   a CEROD databas
2c3e0 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
2c3f0 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
2c400 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74  f the CEROD rout
2c410 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
2c420 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
2c430 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a  activate_cerod(.
2c440 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
2c450 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
2c460 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
2c470 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
2c480 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
2c490 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63  EF: Suspend Exec
2c4a0 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72  ution For A Shor
2c4b0 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  t Time.**.** ^Th
2c4c0 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
2c4d0 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  ) function cause
2c4e0 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
2c4f0 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
2c500 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72  execution.** for
2c510 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62   at least a numb
2c520 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
2c530 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
2c540 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
2c550 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 65  *.** ^If the ope
2c560 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
2c570 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
2c580 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
2c590 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  th.** millisecon
2c5a0 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
2c5b0 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
2c5c0 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
2c5d0 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65   up to.** the ne
2c5e0 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 5e 54  arest second. ^T
2c5f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
2c600 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
2c610 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
2c620 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
2c630 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
2c640 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
2c650 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d  **.** ^SQLite im
2c660 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
2c670 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
2c680 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
2c690 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
2c6a0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
2c6b0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
2c6c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
2c6d0 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
2c6e0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
2c6f0 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
2c700 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
2c710 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  Files.**.** ^(If
2c720 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72   this global var
2c730 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f  iable is made to
2c740 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
2c750 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74  ng which is.** t
2c760 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c  he name of a fol
2c770 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65  der (a.k.a. dire
2c780 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c  ctory), then all
2c790 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
2c7a0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53  .** created by S
2c7b0 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67  QLite when using
2c7c0 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c   a built-in [sql
2c7d0 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a  ite3_vfs | VFS].
2c7e0 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  ** will be place
2c7f0 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
2c800 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73  ory.)^  ^If this
2c810 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20   variable.** is 
2c820 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
2c830 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66  then SQLite perf
2c840 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f  orms a search fo
2c850 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
2c860 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
2c870 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  le directory..**
2c880 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
2c890 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
2c8a0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
2c8b0 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
2c8c0 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
2c8d0 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
2c8e0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
2c8f0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
2c900 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
2c910 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2c920 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
2c930 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
2c940 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
2c950 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
2c960 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
2c970 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
2c980 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
2c990 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
2c9a0 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
2c9b0 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
2c9c0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
2c9d0 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
2c9e0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
2c9f0 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
2ca00 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
2ca10 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
2ca20 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
2ca30 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  The [temp_store_
2ca40 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2ca50 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
2ca60 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
2ca70 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
2ca80 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
2ca90 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2caa0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
2cab0 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
2cac0 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
2cad0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2cae0 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
2caf0 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
2cb00 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
2cb10 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
2cb20 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
2cb30 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
2cb40 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
2cb50 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
2cb60 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
2cb70 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
2cb80 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
2cb90 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
2cba0 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
2cbb0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
2cbc0 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
2cbd0 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
2cbe0 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
2cbf0 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
2cc00 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
2cc10 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2cc20 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
2cc30 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
2cc40 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
2cc50 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2cc60 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
2cc70 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ded..*/.SQLITE_E
2cc80 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
2cc90 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
2cca0 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
2ccb0 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
2ccc0 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a  to-Commit Mode.*
2ccd0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
2cce0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a  ocommit mode}.**
2ccf0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2cd00 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
2cd10 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2cd20 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
2cd30 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
2cd40 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
2cd50 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
2cd60 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
2cd70 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
2cd80 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74  pectively.  ^Aut
2cd90 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2cda0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
2cdb0 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  * ^Autocommit mo
2cdc0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
2cdd0 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  y a [BEGIN] stat
2cde0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63  ement..** ^Autoc
2cdf0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
2ce00 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  -enabled by a [C
2ce10 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
2ce20 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
2ce30 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
2ce40 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
2ce50 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
2ce60 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
2ce70 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
2ce80 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ion (errors incl
2ce90 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
2cea0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
2ceb0 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  RR],.** [SQLITE_
2cec0 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f  NOMEM], [SQLITE_
2ced0 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  BUSY], and [SQLI
2cee0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74  TE_INTERRUPT]) t
2cef0 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73  hen the.** trans
2cf00 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  action might be 
2cf10 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
2cf20 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
2cf30 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66  only way to.** f
2cf40 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20  ind out whether 
2cf50 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
2cf60 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cf70 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2cf80 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
2cf90 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
2cfa0 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
2cfb0 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
2cfc0 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20  ead changes the 
2cfd0 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75  autocommit statu
2cfe0 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  s of the databas
2cff0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2d000 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
2d010 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
2d020 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
2d030 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  alue.** is undef
2d040 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
2d050 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
2d060 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
2d070 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d080 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
2d090 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
2d0a0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2d0b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d0c0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
2d0d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d0e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2d0f0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
2d100 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
2d110 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d120 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54  nt] belongs.  ^T
2d130 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2d140 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75  nection].** retu
2d150 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2d160 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65  db_handle is the
2d170 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
2d180 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
2d190 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
2d1a0 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
2d1b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
2d1c0 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
2d1d0 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
2d1e0 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
2d1f0 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
2d200 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
2d210 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
2d220 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
2d230 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
2d240 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2d250 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2d260 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65  ind the next pre
2d270 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2d280 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
2d290 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2d2a0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
2d2b0 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ext [prepared st
2d2c0 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a  atement] after.*
2d2d0 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74  * pStmt associat
2d2e0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
2d2f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d300 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d  ] pDb.  ^If pStm
2d310 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65  t is NULL.** the
2d320 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  n this interface
2d330 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2d340 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  er to the first 
2d350 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d360 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  nt.** associated
2d370 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
2d380 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44  se connection pD
2d390 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61  b.  ^If no prepa
2d3a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2d3b0 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63   satisfies the c
2d3c0 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69  onditions of thi
2d3d0 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65  s routine, it re
2d3e0 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  turns NULL..**.*
2d3f0 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20  * The [database 
2d400 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e  connection] poin
2d410 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20  ter D in a call 
2d420 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e  to.** [sqlite3_n
2d430 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d  ext_stmt(D,S)] m
2d440 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20  ust refer to an 
2d450 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  open database.**
2d460 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20   connection and 
2d470 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75  in particular mu
2d480 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c  st not be a NULL
2d490 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c   pointer..*/.sql
2d4a0 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74  ite3_stmt *sqlit
2d4b0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c  e3_next_stmt(sql
2d4c0 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74  ite3 *pDb, sqlit
2d4d0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2d4e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d4f0 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c  : Commit And Rol
2d500 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69  lback Notificati
2d510 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
2d520 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d530 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e  commit_hook() in
2d540 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2d550 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
2d560 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
2d570 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2d580 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2d590 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69   [COMMIT | commi
2d5a0 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  tted]..** ^Any c
2d5b0 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
2d5c0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2d5d0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
2d5e0 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
2d5f0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2d600 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2d610 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
2d620 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  he sqlite3_rollb
2d630 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ack_hook() inter
2d640 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
2d650 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
2d660 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
2d670 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
2d680 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52  ransaction is [R
2d690 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64  OLLBACK | rolled
2d6a0 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20   back]..** ^Any 
2d6b0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
2d6c0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
2d6d0 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  to sqlite3_rollb
2d6e0 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  ack_hook().** fo
2d6f0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
2d700 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2d710 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
2d720 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d   ^The pArg argum
2d730 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68  ent is passed th
2d740 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c  rough to the cal
2d750 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68  lback..** ^If th
2d760 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
2d770 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
2d780 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e  tion returns non
2d790 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74  -zero,.** then t
2d7a0 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
2d7b0 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
2d7c0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
2d7d0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
2d7e0 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e  t_hook(D,C,P) an
2d7f0 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  d sqlite3_rollba
2d800 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66  ck_hook(D,C,P) f
2d810 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75  unctions.** retu
2d820 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e  rn the P argumen
2d830 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
2d840 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20  ous call of the 
2d850 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
2d860 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
2d870 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d880 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f  n] D, or NULL fo
2d890 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63  r.** the first c
2d8a0 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e  all for each fun
2d8b0 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a  ction on D..**.*
2d8c0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  * The callback i
2d8d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2d8e0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
2d8f0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
2d900 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
2d910 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
2d920 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
2d930 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61  callback.  Any a
2d940 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
2d950 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2d960 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
2d970 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
2d980 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
2d990 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
2d9a0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2d9b0 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
2d9c0 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69  ggered the commi
2d9d0 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  t.** or rollback
2d9e0 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72   hook in the fir
2d9f0 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74  st place..** Not
2da00 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
2da10 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2da20 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
2da30 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
2da40 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
2da50 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
2da60 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
2da70 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
2da80 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
2da90 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61  * ^Registering a
2daa0 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64   NULL function d
2dab0 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c  isables the call
2dac0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  back..**.** ^Whe
2dad0 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  n the commit hoo
2dae0 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  k callback routi
2daf0 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ne returns zero,
2db00 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a   the [COMMIT].**
2db10 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c   operation is al
2db20 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75  lowed to continu
2db30 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66  e normally.  ^If
2db40 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
2db50 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
2db60 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b  zero, then the [
2db70 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65  COMMIT] is conve
2db80 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c  rted into a [ROL
2db90 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20  LBACK]..** ^The 
2dba0 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73  rollback hook is
2dbb0 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f   invoked on a ro
2dbc0 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75  llback that resu
2dbd0 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69  lts from a commi
2dbe0 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e  t.** hook return
2dbf0 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75  ing non-zero, ju
2dc00 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62  st as it would b
2dc10 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72  e with any other
2dc20 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
2dc30 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
2dc40 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
2dc50 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2dc60 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
2dc70 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  en.** rolled bac
2dc80 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74  k if an explicit
2dc90 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74   "ROLLBACK" stat
2dca0 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
2dcb0 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  d, or.** an erro
2dcc0 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20  r or constraint 
2dcd0 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63  causes an implic
2dce0 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f  it rollback to o
2dcf0 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ccur..** ^The ro
2dd00 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
2dd10 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
2dd20 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
2dd30 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
2dd40 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
2dd50 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
2dd60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2dd70 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
2dd80 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
2dd90 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2dda0 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ok()] interface.
2ddb0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2ddc0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71  3_commit_hook(sq
2ddd0 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
2dde0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  oid*), void*);.v
2ddf0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
2de00 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
2de10 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
2de20 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
2de30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2de40 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
2de50 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
2de60 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2de70 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2de80 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
2de90 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
2dea0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  k function.** wi
2deb0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
2dec0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65   connection] ide
2ded0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ntified by the f
2dee0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
2def0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2df00 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
2df10 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
2df20 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
2df30 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
2df40 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2df50 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
2df60 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74  unction.** for t
2df70 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2df80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2df90 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
2dfa0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
2dfb0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
2dfc0 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
2dfd0 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
2dfe0 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70  n a.** row is up
2dff0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
2e000 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  or deleted..** ^
2e010 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2e020 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  nt to the callba
2e030 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
2e040 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
2e050 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
2e060 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a  _update_hook()..
2e070 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63  ** ^The second c
2e080 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
2e090 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
2e0a0 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c  TE_INSERT], [SQL
2e0b0 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20  ITE_DELETE],.** 
2e0c0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54  or [SQLITE_UPDAT
2e0d0 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  E], depending on
2e0e0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
2e0f0 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
2e100 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65  allback.** to be
2e110 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
2e120 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
2e130 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
2e140 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
2e150 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f  tain pointers to
2e160 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2e170 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20   and table name 
2e180 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
2e190 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20  ffected row..** 
2e1a0 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62  ^The final callb
2e1b0 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
2e1c0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
2e1d0 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20  the row..** ^In 
2e1e0 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75  the case of an u
2e1f0 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74  pdate, this is t
2e200 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72  he [rowid] after
2e210 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
2e220 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  s place..**.** ^
2e230 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b  (The update hook
2e240 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2e250 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79  when internal sy
2e260 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a  stem tables are.
2e270 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65  ** modified (i.e
2e280 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20  . sqlite_master 
2e290 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65  and sqlite_seque
2e2a0 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  nce).)^.**.** ^I
2e2b0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  n the current im
2e2c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68  plementation, th
2e2d0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
2e2e0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2e2f0 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e  when duplication
2e300 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
2e310 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a  d because of an.
2e320 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  ** [ON CONFLICT 
2e330 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45  | ON CONFLICT RE
2e340 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20  PLACE] clause.  
2e350 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61  ^Nor is the upda
2e360 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b  te hook.** invok
2e370 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65  ed when rows are
2e380 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74   deleted using t
2e390 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  he [truncate opt
2e3a0 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  imization]..** T
2e3b0 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65  he exceptions de
2e3c0 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61  fined in this pa
2e3d0 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68  ragraph might ch
2e3e0 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
2e3f0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
2e400 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
2e410 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70   update hook imp
2e420 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
2e430 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
2e440 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
2e450 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
2e460 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
2e470 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70  t invoked the up
2e480 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20  date hook.  Any 
2e490 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f  actions.** to mo
2e4a0 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
2e4b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2e4c0 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  t be deferred un
2e4d0 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  til after the.**
2e4e0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74   completion of t
2e4f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
2e500 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ()] call that tr
2e510 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61  iggered the upda
2e520 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65  te hook..** Note
2e530 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
2e540 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2e550 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2e560 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
2e570 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
2e580 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
2e590 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
2e5a0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
2e5b0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
2e5c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70   ^The sqlite3_up
2e5d0 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  date_hook(D,C,P)
2e5e0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74   function.** ret
2e5f0 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d  urns the P argum
2e600 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
2e610 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e  vious call.** on
2e620 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
2e630 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2e640 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a  D, or NULL for.*
2e650 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  * the first call
2e660 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   on D..**.** See
2e670 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
2e680 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
2e690 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
2e6a0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a  ollback_hook()].
2e6b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  ** interfaces..*
2e6c0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
2e6d0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73  update_hook(.  s
2e6e0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2e6f0 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c  (*)(void *,int ,
2e700 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61  char const *,cha
2e710 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65  r const *,sqlite
2e720 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64  3_int64),.  void
2e730 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.);../*.** CAPI
2e740 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
2e750 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50  Disable Shared P
2e760 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45  ager Cache.** KE
2e770 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20  YWORDS: {shared 
2e780 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54  cache}.**.** ^(T
2e790 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  his routine enab
2e7a0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
2e7b0 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74  the sharing of t
2e7c0 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68  he database cach
2e7d0 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20  e.** and schema 
2e7e0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
2e7f0 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73  between [databas
2e800 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63  e connection | c
2e810 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74  onnections].** t
2e820 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
2e830 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20  ase. Sharing is 
2e840 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
2e850 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a  rgument is true.
2e860 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ** and disabled 
2e870 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
2e880 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a  is false.)^.**.*
2e890 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67  * ^Cache sharing
2e8a0 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
2e8b0 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20  disabled for an 
2e8c0 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a  entire process..
2e8d0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61  ** This is a cha
2e8e0 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
2e8f0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20   version 3.5.0. 
2e900 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
2e910 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  s of SQLite,.** 
2e920 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62  sharing was enab
2e930 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
2e940 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
2e950 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2e960 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68  * ^(The cache sh
2e970 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62  aring mode set b
2e980 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
2e990 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62   effects all sub
2e9a0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
2e9b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
2e9c0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2e9d0 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b  pen_v2()], and [
2e9e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2e9f0 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64  ]..** Existing d
2ea00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ea10 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65  ons continue use
2ea20 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64   the sharing mod
2ea30 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e  e.** that was in
2ea40 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74   effect at the t
2ea50 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70  ime they were op
2ea60 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  ened.)^.**.** ^(
2ea70 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
2ea80 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
2ea90 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
2eaa0 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
2eab0 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63  disabled.** succ
2eac0 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65  essfully.  An [e
2ead0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2eae0 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65  turned otherwise
2eaf0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65  .)^.**.** ^Share
2eb00 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
2eb10 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20  led by default. 
2eb20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63  But this might c
2eb30 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75  hange in.** futu
2eb40 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2eb50 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74  QLite.  Applicat
2eb60 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61  ions that care a
2eb70 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63  bout shared.** c
2eb80 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f  ache setting sho
2eb90 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69  uld set it expli
2eba0 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  citly..**.** See
2ebb0 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20   Also:  [SQLite 
2ebc0 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64  Shared-Cache Mod
2ebd0 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e].*/.int sqlite
2ebe0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
2ebf0 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  cache(int);../*.
2ec00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74  ** CAPI3REF: Att
2ec10 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61  empt To Free Hea
2ec20 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e  p Memory.**.** ^
2ec30 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
2ec40 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74  ase_memory() int
2ec50 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
2ec60 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a  to free N bytes.
2ec70 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  ** of heap memor
2ec80 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e  y by deallocatin
2ec90 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  g non-essential 
2eca0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2ecb0 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68  ns.** held by th
2ecc0 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
2ecd0 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65  ry.   Memory use
2ece0 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62  d to cache datab
2ecf0 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20  ase.** pages to 
2ed00 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
2ed10 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  nce is an exampl
2ed20 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  e of non-essenti
2ed30 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73  al memory..** ^s
2ed40 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2ed50 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20  emory() returns 
2ed60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2ed70 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
2ed80 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67  ed,.** which mig
2ed90 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65  ht be more or le
2eda0 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75  ss than the amou
2edb0 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f  nt requested..*/
2edc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
2edd0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
2ede0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2edf0 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69  F: Impose A Limi
2ee00 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a  t On Heap Size.*
2ee10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ee20 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
2ee30 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70 6c  t() interface pl
2ee40 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69  aces a "soft" li
2ee50 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d  mit.** on the am
2ee60 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
2ee70 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
2ee80 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
2ee90 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 69  ite..** ^If an i
2eea0 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69  nternal allocati
2eeb0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20  on is requested 
2eec0 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65  that would excee
2eed0 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65  d the.** soft he
2eee0 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74  ap limit, [sqlit
2eef0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2ef00 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20  y()] is invoked 
2ef10 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  one or.** more t
2ef20 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20  imes to free up 
2ef30 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72  some space befor
2ef40 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  e the allocation
2ef50 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a   is performed..*
2ef60 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69 74 20  *.** ^The limit 
2ef70 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22  is called "soft"
2ef80 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c   because if [sql
2ef90 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2efa0 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74  ory()].** cannot
2efb0 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74   free sufficient
2efc0 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65   memory to preve
2efd0 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f  nt the limit fro
2efe0 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64  m being exceeded
2eff0 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  ,.** the memory 
2f000 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79  is allocated any
2f010 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72  way and the curr
2f020 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  ent operation pr
2f030 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  oceeds..**.** ^A
2f040 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72   negative or zer
2f050 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65  o value for N me
2f060 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69  ans that there i
2f070 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c  s no soft heap l
2f080 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  imit and.** [sql
2f090 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2f0a0 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79  ory()] will only
2f0b0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2f0c0 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73  memory is exhaus
2f0d0 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ted..** ^The def
2f0e0 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
2f0f0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
2f100 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  it is zero..**.*
2f110 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b 65 73  * ^(SQLite makes
2f120 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74   a best effort t
2f130 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74  o honor the soft
2f140 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20   heap limit..** 
2f150 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20  But if the soft 
2f160 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f  heap limit canno
2f170 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78  t be honored, ex
2f180 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20  ecution will.** 
2f190 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74  continue without
2f1a0 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69   error or notifi
2f1b0 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69 73 20  cation.)^  This 
2f1c0 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74  is why the limit
2f1d0 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20   is.** called a 
2f1e0 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49  "soft" limit.  I
2f1f0 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e  t is advisory on
2f200 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ly..**.** Prior 
2f210 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
2f220 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f  n 3.5.0, this ro
2f230 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74  utine only const
2f240 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72  rained the memor
2f250 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62  y.** allocated b
2f260 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
2f270 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72  d - the same thr
2f280 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69  ead in which thi
2f290 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e  s routine.** run
2f2a0 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69  s.  Beginning wi
2f2b0 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  th SQLite versio
2f2c0 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66  n 3.5.0, the sof
2f2d0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a  t heap limit is.
2f2e0 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c  ** applied to al
2f2f0 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76  l threads. The v
2f300 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66  alue specified f
2f310 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2f320 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20   limit.** is an 
2f330 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74  upper bound on t
2f340 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20  he total memory 
2f350 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61  allocation for a
2f360 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a  ll threads. In.*
2f370 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  * version 3.5.0 
2f380 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68  there is no mech
2f390 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69  anism for limiti
2f3a0 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67  ng the heap usag
2f3b0 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64  e for.** individ
2f3c0 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a  ual threads..*/.
2f3d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66  void sqlite3_sof
2f3e0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74  t_heap_limit(int
2f3f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f400 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61  EF: Extract Meta
2f410 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c  data About A Col
2f420 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a  umn Of A Table.*
2f430 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
2f440 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64  ne returns metad
2f450 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
2f460 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
2f470 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74   specific.** dat
2f480 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65  abase table acce
2f490 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
2f4a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f4b0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
2f4c0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
2f4d0 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72  irst function ar
2f4e0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2f4f0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65  he column is ide
2f500 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
2f510 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64  econd, third and
2f520 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2f530 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75  rs to.** this fu
2f540 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63  nction. ^The sec
2f550 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2f560 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65   either the name
2f570 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2f580 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22  .** (i.e. "main"
2f590 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20  , "temp", or an 
2f5a0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2f5b0 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  e) containing th
2f5c0 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74  e specified.** t
2f5d0 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49  able or NULL. ^I
2f5e0 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
2f5f0 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20  en all attached 
2f600 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65  databases are se
2f610 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68  arched.** for th
2f620 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68  e table using th
2f630 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
2f640 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74   used by the dat
2f650 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a  abase engine to.
2f660 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61  ** resolve unqua
2f670 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66  lified table ref
2f680 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  erences..**.** ^
2f690 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2f6a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
2f6b0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
2f6c0 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61   are the table a
2f6d0 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d  nd column.** nam
2f6e0 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64  e of the desired
2f6f0 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74   column, respect
2f700 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f  ively. Neither o
2f710 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
2f720 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rs.** may be NUL
2f730 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61  L..**.** ^Metada
2f740 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ta is returned b
2f750 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65  y writing to the
2f760 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e   memory location
2f770 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
2f780 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65  5th.** and subse
2f790 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73  quent parameters
2f7a0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
2f7b0 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65  n. ^Any of these
2f7c0 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62   arguments may b
2f7d0 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68  e.** NULL, in wh
2f7e0 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72  ich case the cor
2f7f0 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65  responding eleme
2f800 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69  nt of metadata i
2f810 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a  s omitted..**.**
2f820 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a   ^(<blockquote>.
2f830 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
2f840 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
2f850 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e  > Parameter <th>
2f860 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20   Output<br>Type 
2f870 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f  <th>  Descriptio
2f880 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2f890 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   5th <td> const 
2f8a0 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20  char* <td> Data 
2f8b0 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  type.** <tr><td>
2f8c0 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   6th <td> const 
2f8d0 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20  char* <td> Name 
2f8e0 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61  of default colla
2f8f0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a  tion sequence.**
2f900 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74   <tr><td> 7th <t
2f910 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c  d> int         <
2f920 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75  td> True if colu
2f930 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c  mn has a NOT NUL
2f940 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  L constraint.** 
2f950 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64  <tr><td> 8th <td
2f960 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
2f970 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
2f980 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  n is part of the
2f990 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20   PRIMARY KEY.** 
2f9a0 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64  <tr><td> 9th <td
2f9b0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
2f9c0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
2f9d0 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d  n is [AUTOINCREM
2f9e0 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ENT].** </table>
2f9f0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2fa00 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  >)^.**.** ^The m
2fa10 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f  emory pointed to
2fa20 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65   by the characte
2fa30 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  r pointers retur
2fa40 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64  ned for the.** d
2fa50 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20  eclaration type 
2fa60 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  and collation se
2fa70 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20  quence is valid 
2fa80 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e  only until the n
2fa90 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61  ext.** call to a
2faa0 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75  ny SQLite API fu
2fab0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nction..**.** ^I
2fac0 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
2fad0 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c  table is actuall
2fae0 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72  y a view, an [er
2faf0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
2fb00 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  urned..**.** ^If
2fb10 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63   the specified c
2fb20 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22  olumn is "rowid"
2fb30 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77  , "oid" or "_row
2fb40 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b  id_" and an.** [
2fb50 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
2fb60 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20  KEY] column has 
2fb70 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20  been explicitly 
2fb80 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74  declared, then t
2fb90 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
2fba0 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
2fbb0 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74  for the explicit
2fbc0 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
2fbd0 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69  mn. ^(If there i
2fbe0 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74  s no.** explicit
2fbf0 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54  ly declared [INT
2fc00 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
2fc10 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  ] column, then t
2fc20 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
2fc30 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
2fc40 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
2fc50 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64  * <pre>.**     d
2fc60 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47  ata type: "INTEG
2fc70 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61  ER".**     colla
2fc80 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22  tion sequence: "
2fc90 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e  BINARY".**     n
2fca0 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20  ot null: 0.**   
2fcb0 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31    primary key: 1
2fcc0 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63  .**     auto inc
2fcd0 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70  rement: 0.** </p
2fce0 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  re>)^.**.** ^(Th
2fcf0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
2fd00 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
2fd10 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
2fd20 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
2fd30 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
2fd40 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
2fd50 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
2fd60 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
2fd70 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
2fd80 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
2fd90 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
2fda0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
2fdb0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
2fdc0 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65  e left.** in the
2fdd0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2fde0 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65  ction] (to be re
2fdf0 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71  trieved using sq
2fe00 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e  lite3_errmsg()).
2fe10 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41  )^.**.** ^This A
2fe20 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  PI is only avail
2fe30 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
2fe40 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
2fe50 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
2fe60 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
2fe70 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
2fe80 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
2fe90 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69  ol defined..*/.i
2fea0 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
2feb0 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
2fec0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2fed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fee0 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
2fef0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2ff00 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
2ff10 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2ff20 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
2ff30 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2ff40 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
2ff50 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
2ff60 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2ff70 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
2ff80 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
2ff90 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
2ffa0 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
2ffb0 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
2ffc0 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
2ffd0 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
2ffe0 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
2fff0 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
30000 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
30010 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
30020 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
30030 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
30040 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
30050 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
30060 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
30070 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
30080 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
30090 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
300a0 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
300b0 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
300c0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
300d0 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
300e0 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
300f0 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
30100 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
30110 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a  n Extension.**.*
30120 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
30130 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74  e loads an SQLit
30140 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72  e extension libr
30150 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d  ary from the nam
30160 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed file..**.** ^
30170 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
30180 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
30190 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
301a0 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51  to load an.** SQ
301b0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
301c0 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64  ibrary contained
301d0 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69   in the file zFi
301e0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65  le..**.** ^The e
301f0 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50  ntry point is zP
30200 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d  roc..** ^zProc m
30210 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63  ay be 0, in whic
30220 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
30230 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
30240 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74  nt.** defaults t
30250 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
30260 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e  sion_init"..** ^
30270 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
30280 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
30290 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
302a0 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  * [SQLITE_OK] on
302b0 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
302c0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
302d0 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
302e0 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ong..** ^If an e
302f0 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20  rror occurs and 
30300 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20  pzErrMsg is not 
30310 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  0, then the.** [
30320 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
30330 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
30340 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70  ace shall attemp
30350 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a  t to.** fill *pz
30360 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f  ErrMsg with erro
30370 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73  r message text s
30380 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  tored in memory.
30390 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
303a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
303b0 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67  ()]. The calling
303c0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f   function.** sho
303d0 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65  uld free this me
303e0 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20  mory by calling 
303f0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
30400 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69  ..**.** ^Extensi
30410 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20  on loading must 
30420 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  be enabled using
30430 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  .** [sqlite3_ena
30440 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
30450 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63  on()] prior to c
30460 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c  alling this API,
30470 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
30480 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
30490 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
304a0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61  ee also the [loa
304b0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51  d_extension() SQ
304c0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a  L function]..*/.
304d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
304e0 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
304f0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
30500 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
30510 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
30520 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
30530 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
30540 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
30550 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
30560 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
30570 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
30580 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
30590 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
305a0 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
305b0 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
305c0 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
305d0 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
305e0 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
305f0 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
30600 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
30610 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
30620 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
30630 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
30640 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20  ng.**.** ^So as 
30650 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75  not to open secu
30660 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c  rity holes in ol
30670 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  der applications
30680 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70   that are.** unp
30690 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20  repared to deal 
306a0 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c  with extension l
306b0 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61  oading, and as a
306c0 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c   means of disabl
306d0 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  ing.** extension
306e0 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65   loading while e
306f0 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65  valuating user-e
30700 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20  ntered SQL, the 
30710 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a  following API.**
30720 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
30730 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
30740 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
30750 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e  ()] mechanism on
30760 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20   and off..**.** 
30770 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69  ^Extension loadi
30780 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  ng is off by def
30790 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74  ault. See ticket
307a0 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c   #1863..** ^Call
307b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61   the sqlite3_ena
307c0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
307d0 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74  on() routine wit
307e0 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f  h onoff==1.** to
307f0 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
30800 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63  loading on and c
30810 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66  all it with onof
30820 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20  f==0 to turn.** 
30830 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69  it back off agai
30840 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
30850 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
30860 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
30870 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
30880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30890 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  : Automatically 
308a0 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f  Load An Extensio
308b0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41  ns.**.** ^This A
308c0 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65  PI can be invoke
308d0 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61  d at program sta
308e0 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f  rtup in order to
308f0 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65   register.** one
30900 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61   or more statica
30910 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e  lly linked exten
30920 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20  sions that will 
30930 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  be available.** 
30940 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61  to all new [data
30950 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
30960 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ]..**.** ^(This 
30970 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61  routine stores a
30980 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
30990 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20  extension entry 
309a0 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e 20 61  point.** in an a
309b0 72 72 61 79 20 74 68 61 74 20 69 73 20 6f 62 74  rray that is obt
309c0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
309d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
309e0 54 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69  That memory.** i
309f0 73 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  s deallocated by
30a00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f   [sqlite3_reset_
30a10 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
30a20 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ].)^.**.** ^This
30a30 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
30a40 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e  ers an extension
30a50 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61   entry point tha
30a60 74 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  t is.** automati
30a70 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68  cally invoked wh
30a80 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b 64 61  enever a new [da
30a90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30aa0 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65 64 20  n].** is opened 
30ab0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  using [sqlite3_o
30ac0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
30ad0 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f  _open16()],.** o
30ae0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
30af0 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70 6c 69  v2()]..** ^Dupli
30b00 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20  cate extensions 
30b10 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20  are detected so 
30b20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  calling this rou
30b30 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  tine.** multiple
30b40 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
30b50 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69  same extension i
30b60 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 20 5e  s harmless..** ^
30b70 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  Automatic extens
30b80 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73  ions apply acros
30b90 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a  s all threads..*
30ba0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75  /.int sqlite3_au
30bb0 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69  to_extension(voi
30bc0 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29  d (*xEntryPoint)
30bd0 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void));../*.** 
30be0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
30bf0 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73  Automatic Extens
30c00 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a  ion Loading.**.*
30c10 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f  * ^(This functio
30c20 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70  n disables all p
30c30 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
30c40 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a  ered automatic.*
30c50 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 49 74  * extensions. It
30c60 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
30c70 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a  ct of all prior.
30c80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f  ** [sqlite3_auto
30c90 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61  _extension()] ca
30ca0 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lls.)^.**.** ^Th
30cb0 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  is function disa
30cc0 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 20 65  bles automatic e
30cd0 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c  xtensions in all
30ce0 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69   threads..*/.voi
30cf0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f  d sqlite3_reset_
30d00 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
30d10 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  oid);../*.** The
30d20 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
30d30 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
30d40 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72  mechanism is cur
30d50 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
30d60 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
30d70 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
30d80 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
30d90 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
30da0 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
30db0 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
30dc0 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
30dd0 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
30de0 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
30df0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
30e00 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
30e10 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
30e20 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
30e30 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
30e40 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
30e50 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
30e60 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
30e70 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
30e80 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74  */../*.** Struct
30e90 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65  ures used by the
30ea0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
30eb0 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65  nterface.*/.type
30ec0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
30ed0 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f  e3_vtab sqlite3_
30ee0 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74  vtab;.typedef st
30ef0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
30f00 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f  ex_info sqlite3_
30f10 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65  index_info;.type
30f20 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
30f30 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73  e3_vtab_cursor s
30f40 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
30f50 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  or;.typedef stru
30f60 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
30f70 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  e sqlite3_module
30f80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30f90 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
30fa0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
30fb0 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64  RDS: sqlite3_mod
30fc0 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62  ule {virtual tab
30fd0 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a  le module}.**.**
30fe0 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c   This structure,
30ff0 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65   sometimes calle
31000 64 20 61 20 61 20 22 76 69 72 74 75 61 6c 20 74  d a a "virtual t
31010 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a  able module", .*
31020 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d  * defines the im
31030 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
31040 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
31050 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74  s].  .** This st
31060 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73  ructure consists
31070 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f   mostly of metho
31080 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
31090 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74  e..**.** ^A virt
310a0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
310b0 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20 66   is created by f
310c0 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73  illing in a pers
310d0 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e  istent.** instan
310e0 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
310f0 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67  ture and passing
31100 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
31110 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74  at instance.** t
31120 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
31130 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b  e_module()] or [
31140 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
31150 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  odule_v2()]..** 
31160 5e 54 68 65 20 72 65 67 69 73 74 72 61 74 69 6f  ^The registratio
31170 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20  n remains valid 
31180 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c  until it is repl
31190 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65 72  aced by a differ
311a0 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72  ent.** module or
311b0 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61   until the [data
311c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
311d0 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f   closes.  The co
311e0 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73  ntent.** of this
311f0 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
31200 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65  not change while
31210 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72 65   it is registere
31220 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61  d with.** any da
31230 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31240 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  n..*/.struct sql
31250 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20  ite3_module {.  
31260 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
31270 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73  int (*xCreate)(s
31280 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
31290 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
312a0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
312b0 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
312c0 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
312d0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
312e0 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
312f0 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  **);.  int (*xCo
31300 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c  nnect)(sqlite3*,
31310 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
31320 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
31330 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
31340 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
31350 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
31360 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
31370 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
31380 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29  nt (*xBestIndex)
31390 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
313a0 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e  VTab, sqlite3_in
313b0 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e  dex_info*);.  in
313c0 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29  t (*xDisconnect)
313d0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
313e0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
313f0 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33  Destroy)(sqlite3
31400 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
31410 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
31420 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
31430 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  b, sqlite3_vtab_
31440 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f  cursor **ppCurso
31450 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  r);.  int (*xClo
31460 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  se)(sqlite3_vtab
31470 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
31480 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69   (*xFilter)(sqli
31490 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
314a0 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f  , int idxNum, co
314b0 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72  nst char *idxStr
314c0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
314d0 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69    int argc, sqli
314e0 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76  te3_value **argv
314f0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74  );.  int (*xNext
31500 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
31510 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
31520 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76  *xEof)(sqlite3_v
31530 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
31540 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73  int (*xColumn)(s
31550 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
31560 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  or*, sqlite3_con
31570 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  text*, int);.  i
31580 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c  nt (*xRowid)(sql
31590 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
315a0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
315b0 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74   *pRowid);.  int
315c0 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69   (*xUpdate)(sqli
315d0 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c  te3_vtab *, int,
315e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
315f0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
31600 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65   *);.  int (*xBe
31610 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  gin)(sqlite3_vta
31620 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
31630 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
31640 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
31650 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29    int (*xCommit)
31660 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
31670 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
31680 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65  Rollback)(sqlite
31690 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
316a0 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e    int (*xFindFun
316b0 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76  ction)(sqlite3_v
316c0 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20  tab *pVtab, int 
316d0 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72  nArg, const char
316e0 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20   *zName,.       
316f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31700 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28  void (**pxFunc)(
31710 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31720 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
31730 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20  ue**),.         
31740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
31750 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69  id **ppArg);.  i
31760 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71  nt (*xRename)(sq
31770 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
31780 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
31790 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  New);.};../*.** 
317a0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
317b0 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67  l Table Indexing
317c0 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   Information.** 
317d0 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
317e0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a  3_index_info.**.
317f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
31800 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74  ndex_info struct
31810 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73  ure and its subs
31820 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65  tructures is use
31830 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66  d to.** pass inf
31840 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e  ormation into an
31850 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65  d receive the re
31860 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42  ply from the [xB
31870 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74  estIndex].** met
31880 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61  hod of a [virtua
31890 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
318a0 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64    The fields und
318b0 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72  er **Inputs** ar
318c0 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20  e the.** inputs 
318d0 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e  to xBestIndex an
318e0 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e  d are read-only.
318f0 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73    xBestIndex ins
31900 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75  erts its.** resu
31910 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f  lts into the **O
31920 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e  utputs** fields.
31930 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f  .**.** ^(The aCo
31940 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
31950 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63   records WHERE c
31960 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
31970 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a  s of the form:.*
31980 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e  *.** <pre>column
31990 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a   OP expr</pre>.*
319a0 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73  *.** where OP is
319b0 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c   =, &lt;, &lt;=,
319c0 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e   &gt;, or &gt;=.
319d0 29 5e 20 20 5e 28 54 68 65 20 70 61 72 74 69 63  )^  ^(The partic
319e0 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73  ular operator is
319f0 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43  .** stored in aC
31a00 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 29  onstraint[].op.)
31a10 5e 20 20 5e 28 54 68 65 20 69 6e 64 65 78 20 6f  ^  ^(The index o
31a20 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
31a30 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f  stored in.** aCo
31a40 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75  nstraint[].iColu
31a50 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74 72  mn.)^  ^(aConstr
31a60 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73  aint[].usable is
31a70 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20   TRUE if the.** 
31a80 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68  expr on the righ
31a90 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20  t-hand side can 
31aa0 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e  be evaluated (an
31ab0 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74  d thus the const
31ac0 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62  raint.** is usab
31ad0 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66  le) and false if
31ae0 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a   it cannot.)^.**
31af0 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a  .** ^The optimiz
31b00 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  er automatically
31b10 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f   inverts terms o
31b20 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72  f the form "expr
31b30 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61   OP column".** a
31b40 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73  nd makes other s
31b50 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74  implifications t
31b60 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75  o the WHERE clau
31b70 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74  se in an attempt
31b80 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61   to.** get as ma
31b90 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ny WHERE clause 
31ba0 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66  terms into the f
31bb0 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  orm shown above 
31bc0 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20  as possible..** 
31bd0 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74  ^The aConstraint
31be0 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65  [] array only re
31bf0 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75  ports WHERE clau
31c00 73 65 20 74 65 72 6d 73 20 74 68 61 74 20 61 72  se terms that ar
31c10 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f  e.** relevant to
31c20 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
31c30 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65  virtual table be
31c40 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a  ing queried..**.
31c50 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20  ** ^Information 
31c60 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20  about the ORDER 
31c70 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f  BY clause is sto
31c80 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b  red in aOrderBy[
31c90 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d  ]..** ^Each term
31ca0 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63   of aOrderBy rec
31cb0 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66  ords a column of
31cc0 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
31cd0 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ause..**.** The 
31ce0 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74  [xBestIndex] met
31cf0 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43  hod must fill aC
31d00 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
31d10 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f   with informatio
31d20 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20  n.** about what 
31d30 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61  parameters to pa
31d40 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20  ss to xFilter.  
31d50 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20  ^If argvIndex>0 
31d60 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68  then.** the righ
31d70 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74  t-hand side of t
31d80 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
31d90 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69   aConstraint[] i
31da0 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61  s evaluated.** a
31db0 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61  nd becomes the a
31dc0 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72  rgvIndex-th entr
31dd0 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49 66  y in argv.  ^(If
31de0 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
31df0 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74  e[].omit.** is t
31e00 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f  rue, then the co
31e10 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75  nstraint is assu
31e20 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20  med to be fully 
31e30 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a  handled by the.*
31e40 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * virtual table 
31e50 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b  and is not check
31e60 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69  ed again by SQLi
31e70 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te.)^.**.** ^The
31e80 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50   idxNum and idxP
31e90 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65  tr values are re
31ea0 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65  corded and passe
31eb0 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78  d into the.** [x
31ec0 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a  Filter] method..
31ed0 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65  ** ^[sqlite3_fre
31ee0 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  e()] is used to 
31ef0 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61  free idxPtr if a
31f00 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65  nd only if.** ne
31f10 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69  edToFreeIdxPtr i
31f20 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s true..**.** ^T
31f30 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  he orderByConsum
31f40 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75  ed means that ou
31f50 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74  tput from [xFilt
31f60 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c  er]/[xNext] will
31f70 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65   occur in.** the
31f80 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74   correct order t
31f90 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52  o satisfy the OR
31fa0 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f  DER BY clause so
31fb0 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74   that no separat
31fc0 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65  e.** sorting ste
31fd0 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  p is required..*
31fe0 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61  *.** ^The estima
31ff0 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73  tedCost value is
32000 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
32010 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e  the cost of doin
32020 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75  g the.** particu
32030 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66  lar lookup.  A f
32040 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61  ull scan of a ta
32050 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69  ble with N entri
32060 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a  es should have.*
32070 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20  * a cost of N.  
32080 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20  A binary search 
32090 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20  of a table of N 
320a0 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
320b0 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66  ave a.** cost of
320c0 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c   approximately l
320d0 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  og(N)..*/.struct
320e0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
320f0 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
32100 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73  s */.  int nCons
32110 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
32120 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
32130 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
32140 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63  raint */.  struc
32150 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
32160 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
32170 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
32180 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
32190 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
321a0 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
321b0 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
321c0 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
321d0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
321e0 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
321f0 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
32200 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
32210 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
32220 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
32230 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
32240 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
32250 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
32260 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
32270 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
32280 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43  gnore */.  } *aC
32290 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
322a0 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
322b0 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
322c0 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
322d0 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20  int nOrderBy;   
322e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
322f0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
32300 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
32310 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74  ause */.  struct
32320 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f   sqlite3_index_o
32330 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e  rderby {.     in
32340 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
32350 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
32360 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20  n number */.    
32370 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64   unsigned char d
32380 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  esc;       /* Tr
32390 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61  ue for DESC.  Fa
323a0 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a  lse for ASC. */.
323b0 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20    } *aOrderBy;  
323c0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
323d0 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  The ORDER BY cla
323e0 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70  use */.  /* Outp
323f0 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  uts */.  struct 
32400 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
32410 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b  nstraint_usage {
32420 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64  .    int argvInd
32430 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ex;           /*
32440 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69   if >0, constrai
32450 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72  nt is part of ar
32460 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f  gv to xFilter */
32470 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68  .    unsigned ch
32480 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a  ar omit;      /*
32490 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74   Do not code a t
324a0 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e  est for this con
324b0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a  straint */.  } *
324c0 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
324d0 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20  ;.  int idxNum; 
324e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
324f0 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f  * Number used to
32500 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e   identify the in
32510 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69  dex */.  char *i
32520 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20  dxStr;          
32530 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70      /* String, p
32540 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64  ossibly obtained
32550 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
32560 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65  lloc */.  int ne
32570 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20  edToFreeIdxStr; 
32580 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78       /* Free idx
32590 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65  Str using sqlite
325a0 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65  3_free() if true
325b0 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42   */.  int orderB
325c0 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20  yConsumed;      
325d0 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70   /* True if outp
325e0 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72  ut is already or
325f0 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c  dered */.  doubl
32600 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b  e estimatedCost;
32610 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74        /* Estimat
32620 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67  ed cost of using
32630 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d   this index */.}
32640 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
32650 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
32660 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e  T_EQ    2.#defin
32670 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
32680 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20  ONSTRAINT_GT    
32690 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
326a0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
326b0 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e  T_LE    8.#defin
326c0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
326d0 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20  ONSTRAINT_LT    
326e0 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
326f0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
32700 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66  NT_GE    32.#def
32710 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
32720 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43  _CONSTRAINT_MATC
32730 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  H 64../*.** CAPI
32740 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
32750 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
32760 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
32770 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
32780 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  nes are used to 
32790 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b  register a new [
327a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
327b0 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  dule] name..** ^
327c0 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73  Module names mus
327d0 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  t be registered 
327e0 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69  before.** creati
327f0 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61  ng a new [virtua
32800 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74  l table] using t
32810 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 62 65  he module and be
32820 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20  fore using a.** 
32830 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72  preexisting [vir
32840 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20  tual table] for 
32850 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a  the module..**.*
32860 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61  * ^The module na
32870 6d 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64  me is registered
32880 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
32890 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
328a0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
328b0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
328c0 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  r.  ^The name of
328d0 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67   the module is g
328e0 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20  iven by the .** 
328f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
32900 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
32910 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
32920 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69  nter to.** the i
32930 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
32940 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
32950 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e  ble module].   ^
32960 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61  The fourth.** pa
32970 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
32980 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64  bitrary client d
32990 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
329a0 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
329b0 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b  gh.** into the [
329c0 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43  xCreate] and [xC
329d0 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20  onnect] methods 
329e0 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
329f0 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77  able module.** w
32a00 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61  hen a new virtua
32a10 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20 62 65  l table is be be
32a20 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20 72  ing created or r
32a30 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a  einitialized..**
32a40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32a50 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
32a60 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 68 61  2() interface ha
32a70 73 20 61 20 66 69 66 74 68 20 70 61 72 61 6d 65  s a fifth parame
32a80 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
32a90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64  a pointer to a d
32aa0 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
32ab0 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e 20 20  e pClientData.  
32ac0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20  ^SQLite will.** 
32ad0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
32ae0 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28  uctor function (
32af0 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  if it is not NUL
32b00 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a  L) when SQLite.*
32b10 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  * no longer need
32b20 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74  s the pClientDat
32b30 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  a pointer.  ^The
32b40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32b50 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65  module().** inte
32b60 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c  rface is equival
32b70 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
32b80 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
32b90 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a  ) with a NULL.**
32ba0 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a   destructor..*/.
32bb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
32bc0 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c  te_module(.  sql
32bd0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
32be0 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
32bf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
32c00 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
32c10 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
32c20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
32c30 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
32c40 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
32c50 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
32c60 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65  dule *p,   /* Me
32c70 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
32c80 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
32c90 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20  pClientData     
32ca0 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
32cb0 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
32cc0 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69  xConnect */.);.i
32cd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
32ce0 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73  e_module_v2(.  s
32cf0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
32d00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
32d10 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
32d20 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
32d30 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
32d40 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
32d50 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
32d60 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
32d70 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
32d80 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
32d90 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
32da0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
32db0 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20   *pClientData,  
32dc0 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
32dd0 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
32de0 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20  e/xConnect */.  
32df0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
32e00 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f  void*)     /* Mo
32e10 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20  dule destructor 
32e20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a  function */.);..
32e30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32e40 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e  Virtual Table In
32e50 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  stance Object.**
32e60 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
32e70 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76  e3_vtab.**.** Ev
32e80 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62  ery [virtual tab
32e90 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65  le module] imple
32ea0 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61  mentation uses a
32eb0 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20   subclass.** of 
32ec0 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f 20 64  this object to d
32ed0 65 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63  escribe a partic
32ee0 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a  ular instance.**
32ef0 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
32f00 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73   table].  Each s
32f10 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20  ubclass will.** 
32f20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74  be tailored to t
32f30 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
32f40 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  s of the module 
32f50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a  implementation..
32f60 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f  ** The purpose o
32f70 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73  f this superclas
32f80 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63  s is to define c
32f90 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68  ertain fields th
32fa0 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e  at are.** common
32fb0 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69   to all module i
32fc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a  mplementations..
32fd0 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74  **.** ^Virtual t
32fe0 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61  ables methods ca
32ff0 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d  n set an error m
33000 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e  essage by assign
33010 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20  ing a.** string 
33020 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
33030 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
33040 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54  ] to zErrMsg.  T
33050 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  he method should
33060 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68  .** take care th
33070 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72  at any prior str
33080 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20  ing is freed by 
33090 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
330a0 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72  e3_free()].** pr
330b0 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67  ior to assigning
330c0 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f   a new string to
330d0 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66 74 65   zErrMsg.  ^Afte
330e0 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
330f0 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65  age.** is delive
33100 72 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c  red up to the cl
33110 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ient application
33120 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  , the string wil
33130 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
33140 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73  ly.** freed by s
33150 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e  qlite3_free() an
33160 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69  d the zErrMsg fi
33170 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f  eld will be zero
33180 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ed..*/.struct sq
33190 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63  lite3_vtab {.  c
331a0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
331b0 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f  ule *pModule;  /
331c0 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72  * The module for
331d0 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61   this virtual ta
331e0 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65  ble */.  int nRe
331f0 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  f;              
33200 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c           /* NO L
33210 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20 20  ONGER USED */.  
33220 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20  char *zErrMsg;  
33230 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33240 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65  /* Error message
33250 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70   from sqlite3_mp
33260 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20  rintf() */.  /* 
33270 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
33280 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
33290 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64  ll typically add
332a0 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
332b0 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  ds */.};../*.** 
332c0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
332d0 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f  l Table Cursor O
332e0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
332f0 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  S: sqlite3_vtab_
33300 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20  cursor {virtual 
33310 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a  table cursor}.**
33320 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75  .** Every [virtu
33330 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
33340 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33350 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20  uses a subclass 
33360 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  of the.** follow
33370 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f  ing structure to
33380 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72   describe cursor
33390 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74  s that point int
333a0 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61  o the.** [virtua
333b0 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65  l table] and are
333c0 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70   used.** to loop
333d0 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72   through the vir
333e0 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72  tual table.  Cur
333f0 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64  sors are created
33400 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
33410 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f  qlite3_module.xO
33420 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74  pen | xOpen] met
33430 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  hod of the modul
33440 65 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f  e and are destro
33450 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73  yed.** by the [s
33460 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43  qlite3_module.xC
33470 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d  lose | xClose] m
33480 65 74 68 6f 64 2e 20 20 43 75 72 73 6f 72 73 20  ethod.  Cursors 
33490 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74  are used.** by t
334a0 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78  he [xFilter], [x
334b0 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b  Next], [xEof], [
334c0 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78  xColumn], and [x
334d0 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a  Rowid] methods.*
334e0 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  * of the module.
334f0 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d    Each module im
33500 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
33510 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  l define.** the 
33520 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72  content of a cur
33530 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f  sor structure to
33540 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65   suit its own ne
33550 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  eds..**.** This 
33560 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74  superclass exist
33570 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65  s in order to de
33580 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74  fine fields of t
33590 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a  he cursor that.*
335a0 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20  * are common to 
335b0 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  all implementati
335c0 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ons..*/.struct s
335d0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
335e0 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76  or {.  sqlite3_v
335f0 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20  tab *pVtab;     
33600 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
33610 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72  e of this cursor
33620 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c   */.  /* Virtual
33630 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
33640 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69  ations will typi
33650 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69  cally add additi
33660 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d  onal fields */.}
33670 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33680 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53  F: Declare The S
33690 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75  chema Of A Virtu
336a0 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e  al Table.**.** ^
336b0 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e  The [xCreate] an
336c0 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74  d [xConnect] met
336d0 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69  hods of a.** [vi
336e0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
336f0 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e  le] call this in
33700 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65  terface.** to de
33710 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74  clare the format
33720 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20   (the names and 
33730 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65  datatypes of the
33740 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20   columns) of.** 
33750 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
33760 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e  es they implemen
33770 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
33780 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73  3_declare_vtab(s
33790 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
337a0 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a  har *zSQL);../*.
337b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65  ** CAPI3REF: Ove
337c0 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e  rload A Function
337d0 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54   For A Virtual T
337e0 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72  able.**.** ^(Vir
337f0 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20  tual tables can 
33800 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74  provide alternat
33810 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ive implementati
33820 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ons of functions
33830 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78  .** using the [x
33840 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65  FindFunction] me
33850 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72  thod of the [vir
33860 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
33870 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f  e].  .** But glo
33880 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  bal versions of 
33890 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a  those functions.
338a0 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e  ** must exist in
338b0 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65   order to be ove
338c0 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  rloaded.)^.**.**
338d0 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b 65   ^(This API make
338e0 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20  s sure a global 
338f0 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e  version of a fun
33900 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72  ction with a par
33910 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20  ticular.** name 
33920 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  and number of pa
33930 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e  rameters exists.
33940 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e    If no such fun
33950 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20  ction exists.** 
33960 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20  before this API 
33970 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77  is called, a new
33980 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65   function is cre
33990 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69 6d  ated.)^  ^The im
339a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
339b0 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  of the new funct
339c0 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65  ion always cause
339d0 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74  s an exception t
339e0 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f  o be thrown.  So
339f0 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63  .** the new func
33a00 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64  tion is not good
33a10 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79   for anything by
33a20 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e   itself.  Its on
33a30 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73  ly.** purpose is
33a40 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f   to be a placeho
33a50 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68  lder function th
33a60 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f  at can be overlo
33a70 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69  aded.** by a [vi
33a80 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f  rtual table]..*/
33a90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65  .int sqlite3_ove
33aa0 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73  rload_function(s
33ab0 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
33ac0 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20  har *zFuncName, 
33ad0 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a  int nArg);../*.*
33ae0 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
33af0 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
33b00 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64  able mechanism d
33b10 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61  efined above (ba
33b20 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f  ck up.** to a co
33b30 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79  mment remarkably
33b40 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73   similar to this
33b50 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74   one) is current
33b60 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
33b70 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
33b80 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
33b90 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
33ba0 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
33bb0 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
33bc0 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
33bd0 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
33be0 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
33bf0 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
33c00 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
33c10 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
33c20 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73  anism stabilizes
33c30 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
33c40 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
33c50 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
33c60 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
33c70 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
33c80 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
33c90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33ca0 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f  A Handle To An O
33cb0 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57  pen BLOB.** KEYW
33cc0 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64  ORDS: {BLOB hand
33cd0 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65  le} {BLOB handle
33ce0 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
33cf0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
33d00 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
33d10 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77  n open BLOB on w
33d20 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
33d30 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
33d40 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
33d50 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  O] can be perfor
33d60 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73  med..** ^Objects
33d70 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72   of this type ar
33d80 65 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71  e created by [sq
33d90 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
33da0 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f  )].** and destro
33db0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
33dc0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  blob_close()]..*
33dd0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
33de0 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64  blob_read()] and
33df0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
33e00 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63  rite()] interfac
33e10 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  es.** can be use
33e20 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69  d to read or wri
33e30 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74  te small subsect
33e40 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ions of the BLOB
33e50 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
33e60 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
33e70 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
33e80 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  ns the size of t
33e90 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73  he BLOB in bytes
33ea0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
33eb0 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  uct sqlite3_blob
33ec0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a   sqlite3_blob;..
33ed0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33ee0 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20  Open A BLOB For 
33ef0 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a  Incremental I/O.
33f00 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
33f10 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20  erfaces opens a 
33f20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68  [BLOB handle | h
33f30 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c  andle] to the BL
33f40 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e  OB located.** in
33f50 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d   row iRow, colum
33f60 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65  n zColumn, table
33f70 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62   zTable in datab
33f80 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f  ase zDb;.** in o
33f90 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
33fa0 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77  same BLOB that w
33fb0 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64  ould be selected
33fc0 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e   by:.**.** <pre>
33fd0 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a  .**     SELECT z
33fe0 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e  Column FROM zDb.
33ff0 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f  zTable WHERE [ro
34000 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20  wid] = iRow;.** 
34010 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  </pre>)^.**.** ^
34020 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  If the flags par
34030 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65  ameter is non-ze
34040 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c 4f  ro, then the BLO
34050 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  B is opened for 
34060 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74  read.** and writ
34070 65 20 61 63 63 65 73 73 2e 20 5e 49 66 20 69 74  e access. ^If it
34080 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c   is zero, the BL
34090 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  OB is opened for
340a0 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a   read access..**
340b0 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73   ^It is not poss
340c0 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63  ible to open a c
340d0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61  olumn that is pa
340e0 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f  rt of an index o
340f0 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65  r primary .** ke
34100 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e  y for writing. ^
34110 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  If [foreign key 
34120 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65  constraints] are
34130 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 20   enabled, it is 
34140 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
34150 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d   to open a colum
34160 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f  n that is part o
34170 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20  f a [child key] 
34180 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a  for writing..**.
34190 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
341a0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20  e database name 
341b0 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e  is not the filen
341c0 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ame that contain
341d0 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  s.** the databas
341e0 65 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65  e but rather the
341f0 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f   symbolic name o
34200 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  f the database t
34210 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 73 20 61  hat.** appears a
34220 66 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77  fter the AS keyw
34230 6f 72 64 20 77 68 65 6e 20 74 68 65 20 64 61 74  ord when the dat
34240 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74  abase is connect
34250 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48  ed using [ATTACH
34260 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 6d  ]..** ^For the m
34270 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
34280 65 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20  e, the database 
34290 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a  name is "main"..
342a0 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74 61 62  ** ^For TEMP tab
342b0 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 73  les, the databas
342c0 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22  e name is "temp"
342d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63  ..**.** ^(On suc
342e0 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  cess, [SQLITE_OK
342f0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
34300 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20  d the new [BLOB 
34310 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74  handle] is writt
34320 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62  en.** to *ppBlob
34330 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  . Otherwise an [
34340 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
34350 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42  eturned and *ppB
34360 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  lob is set.** to
34370 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74   be a null point
34380 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20 66  er.)^.** ^This f
34390 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65  unction sets the
343a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
343b0 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64  ction] error cod
343c0 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a  e and message.**
343d0 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20   accessible via 
343e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
343f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
34400 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 72  _errmsg()] and r
34410 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69  elated.** functi
34420 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74 20  ons. ^Note that 
34430 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 72 69  the *ppBlob vari
34440 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73 20 69  able is always i
34450 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a  nitialized in a.
34460 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65  ** way that make
34470 73 20 69 74 20 73 61 66 65 20 74 6f 20 69 6e 76  s it safe to inv
34480 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  oke [sqlite3_blo
34490 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70  b_close()] on *p
344a0 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c  pBlob.** regardl
344b0 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
344c0 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ss or failure of
344d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a   this routine..*
344e0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 72 6f  *.** ^(If the ro
344f0 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61  w that a BLOB ha
34500 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69  ndle points to i
34510 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e  s modified by an
34520 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44  .** [UPDATE], [D
34530 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f  ELETE], or by [O
34540 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65  N CONFLICT] side
34550 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e  -effects.** then
34560 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
34570 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65   is marked as "e
34580 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73  xpired"..** This
34590 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20   is true if any 
345a0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f  column of the ro
345b0 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76  w is changed, ev
345c0 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f  en a column.** o
345d0 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e  ther than the on
345e0 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  e the BLOB handl
345f0 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a  e is open on.)^.
34600 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73 71  ** ^Calls to [sq
34610 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
34620 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34630 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f  blob_write()] fo
34640 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42  r.** a expired B
34650 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20  LOB handle fail 
34660 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63  with an return c
34670 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41  ode of [SQLITE_A
34680 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e  BORT]..** ^(Chan
34690 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  ges written into
346a0 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f   a BLOB prior to
346b0 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69   the BLOB expiri
346c0 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f  ng are not.** ro
346d0 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65  lled back by the
346e0 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74   expiration of t
346f0 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68 20 63  he BLOB.  Such c
34700 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76 65 6e  hanges will even
34710 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74  tually.** commit
34720 20 69 66 20 74 68 65 20 74 72 61 6e 73 61 63 74   if the transact
34730 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ion continues to
34740 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a   completion.)^.*
34750 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20 5b 73  *.** ^Use the [s
34760 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
34770 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  s()] interface t
34780 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
34790 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  size of.** the o
347a0 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e 54 68  pened blob.  ^Th
347b0 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62  e size of a blob
347c0 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61 6e   may not be chan
347d0 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 69  ged by this.** i
347e0 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65 20 74  nterface.  Use t
347f0 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c 20  he [UPDATE] SQL 
34800 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67  command to chang
34810 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 0a  e the size of a.
34820 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e  ** blob..**.** ^
34830 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
34840 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e  d_zeroblob()] an
34850 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
34860 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e  t_zeroblob()] in
34870 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20  terfaces.** and 
34880 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65  the built-in [ze
34890 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63  roblob] SQL func
348a0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
348b0 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a  , if desired,.**
348c0 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20 65 6d   to create an em
348d0 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64  pty, zero-filled
348e0 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68 20 74   blob in which t
348f0 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  o read or write 
34900 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e  using.** this in
34910 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
34920 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f 75 72  o avoid a resour
34930 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f  ce leak, every o
34940 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  pen [BLOB handle
34950 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74 75 61  ] should eventua
34960 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73  lly.** be releas
34970 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20  ed by a call to 
34980 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
34990 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ose()]..*/.int s
349a0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
349b0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
349c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c  const char *zDb,
349d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
349e0 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63  Table,.  const c
349f0 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20  har *zColumn,.  
34a00 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52  sqlite3_int64 iR
34a10 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c  ow,.  int flags,
34a20 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  .  sqlite3_blob 
34a30 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a  **ppBlob.);../*.
34a40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
34a50 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65  se A BLOB Handle
34a60 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73 20 61  .**.** ^Closes a
34a70 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e  n open [BLOB han
34a80 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f  dle]..**.** ^Clo
34a90 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c  sing a BLOB shal
34aa0 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72  l cause the curr
34ab0 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ent transaction 
34ac0 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20  to commit.** if 
34ad0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68  there are no oth
34ae0 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e  er BLOBs, no pen
34af0 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74  ding prepared st
34b00 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68  atements, and th
34b10 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
34b20 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b  nnection is in [
34b30 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d  autocommit mode]
34b40 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77 72 69  ..** ^If any wri
34b50 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f  tes were made to
34b60 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20   the BLOB, they 
34b70 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e  might be held in
34b80 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20   cache.** until 
34b90 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74  the close operat
34ba0 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c  ion if they will
34bb0 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c   fit..**.** ^(Cl
34bc0 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f  osing the BLOB o
34bd0 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20  ften forces the 
34be0 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74  changes.** out t
34bf0 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66  o disk and so if
34c00 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20   any I/O errors 
34c10 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c  occur, they will
34c20 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a   likely occur.**
34c30 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
34c40 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c  n the BLOB is cl
34c50 6f 73 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72  osed.  Any error
34c60 73 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72  s that occur dur
34c70 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61  ing.** closing a
34c80 72 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61  re reported as a
34c90 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e   non-zero return
34ca0 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20   value.)^.**.** 
34cb0 5e 28 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c  ^(The BLOB is cl
34cc0 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e  osed uncondition
34cd0 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74  ally.  Even if t
34ce0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
34cf0 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  rns.** an error 
34d00 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69  code, the BLOB i
34d10 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 29  s still closed.)
34d20 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ^.**.** ^Calling
34d30 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
34d40 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65  th a null pointe
34d50 72 20 28 73 75 63 68 20 61 73 20 77 6f 75 6c 64  r (such as would
34d60 20 62 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20   be returned.** 
34d70 62 79 20 61 20 66 61 69 6c 65 64 20 63 61 6c 6c  by a failed call
34d80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
34d90 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20 61 20  b_open()]) is a 
34da0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
34db0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
34dc0 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  lob_close(sqlite
34dd0 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a  3_blob *);../*.*
34de0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75  * CAPI3REF: Retu
34df0 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41  rn The Size Of A
34e00 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a  n Open BLOB.**.*
34e10 2a 20 5e 52 65 74 75 72 6e 73 20 74 68 65 20 73  * ^Returns the s
34e20 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20  ize in bytes of 
34e30 74 68 65 20 42 4c 4f 42 20 61 63 63 65 73 73 69  the BLOB accessi
34e40 62 6c 65 20 76 69 61 20 74 68 65 20 0a 2a 2a 20  ble via the .** 
34e50 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 70 65  successfully ope
34e60 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  ned [BLOB handle
34e70 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72  ] in its only ar
34e80 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 0a 2a 2a  gument.  ^The.**
34e90 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62 6c 6f   incremental blo
34ea0 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73 20 63  b I/O routines c
34eb0 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f 72 20  an only read or 
34ec0 6f 76 65 72 77 72 69 74 69 6e 67 20 65 78 69 73  overwriting exis
34ed0 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e  ting.** blob con
34ee0 74 65 6e 74 3b 20 74 68 65 79 20 63 61 6e 6e 6f  tent; they canno
34ef0 74 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a  t change the siz
34f00 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a  e of a blob..**.
34f10 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
34f20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20  only works on a 
34f30 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68  [BLOB handle] wh
34f40 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65  ich has been cre
34f50 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69  ated.** by a pri
34f60 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
34f70 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
34f80 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  lob_open()] and 
34f90 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a  which has not.**
34fa0 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20   been closed by 
34fb0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
34fc0 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67  ose()].  Passing
34fd0 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74   any other point
34fe0 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73  er in.** to this
34ff0 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73   routine results
35000 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
35010 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
35020 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  irable behavior.
35030 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
35040 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74  blob_bytes(sqlit
35050 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a  e3_blob *);../*.
35060 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 61  ** CAPI3REF: Rea
35070 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c  d Data From A BL
35080 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79  OB Incrementally
35090 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75  .**.** ^(This fu
350a0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  nction is used t
350b0 6f 20 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d  o read data from
350c0 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68   an open [BLOB h
350d0 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a  andle] into a.**
350e0 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64   caller-supplied
350f0 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73   buffer. N bytes
35100 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70   of data are cop
35110 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ied into buffer 
35120 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70  Z.** from the op
35130 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e  en BLOB, startin
35140 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
35150 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  set.)^.**.** ^If
35160 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20   offset iOffset 
35170 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62  is less than N b
35180 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e  ytes from the en
35190 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a  d of the BLOB,.*
351a0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
351b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
351c0 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64   no data is read
351d0 2e 20 20 5e 49 66 20 4e 20 6f 72 20 69 4f 66 66  .  ^If N or iOff
351e0 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74  set is.** less t
351f0 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 54  han zero, [SQLIT
35200 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
35210 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
35220 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20 5e 54 68   is read..** ^Th
35230 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 6c  e size of the bl
35240 6f 62 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68  ob (and hence th
35250 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20  e maximum value 
35260 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a  of N+iOffset).**
35270 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
35280 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  ed using the [sq
35290 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
352a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
352b0 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74  *.** ^An attempt
352c0 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61 6e   to read from an
352d0 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68   expired [BLOB h
352e0 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74  andle] fails wit
352f0 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f  h an.** error co
35300 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42  de of [SQLITE_AB
35310 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  ORT]..**.** ^(On
35320 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65   success, sqlite
35330 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 20 72 65  3_blob_read() re
35340 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e  turns SQLITE_OK.
35350 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61  .** Otherwise, a
35360 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
35370 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65  r an [extended e
35380 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
35390 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
353a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  This routine onl
353b0 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c  y works on a [BL
353c0 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68  OB handle] which
353d0 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65   has been create
353e0 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20  d.** by a prior 
353f0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
35400 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
35410 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69  _open()] and whi
35420 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65  ch has not.** be
35430 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71  en closed by [sq
35440 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
35450 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e  ()].  Passing an
35460 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20  y other pointer 
35470 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f  in.** to this ro
35480 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e  utine results in
35490 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
354a0 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
354b0 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ble behavior..**
354c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
354d0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
354e0 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  e()]..*/.int sql
354f0 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73  ite3_blob_read(s
35500 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76  qlite3_blob *, v
35510 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69  oid *Z, int N, i
35520 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a  nt iOffset);../*
35530 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 57 72  .** CAPI3REF: Wr
35540 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20  ite Data Into A 
35550 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c  BLOB Incremental
35560 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ly.**.** ^This f
35570 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20  unction is used 
35580 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 6e  to write data in
35590 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  to an open [BLOB
355a0 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a   handle] from a.
355b0 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69  ** caller-suppli
355c0 65 64 20 62 75 66 66 65 72 2e 20 5e 4e 20 62 79  ed buffer. ^N by
355d0 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20  tes of data are 
355e0 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20  copied from the 
355f0 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f  buffer Z.** into
35600 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20   the open BLOB, 
35610 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73  starting at offs
35620 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a  et iOffset..**.*
35630 2a 20 5e 49 66 20 74 68 65 20 5b 42 4c 4f 42 20  * ^If the [BLOB 
35640 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61  handle] passed a
35650 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
35660 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70 65  ment was not ope
35670 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74 69  ned for.** writi
35680 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 61  ng (the flags pa
35690 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
356a0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
356b0 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74   was zero),.** t
356c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
356d0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  urns [SQLITE_REA
356e0 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  DONLY]..**.** ^T
356f0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
35700 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65   only modify the
35710 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65   contents of the
35720 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a 20   BLOB; it is.** 
35730 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
35740 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 7a  increase the siz
35750 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 69 6e  e of a BLOB usin
35760 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 5e  g this API..** ^
35770 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  If offset iOffse
35780 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e  t is less than N
35790 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
357a0 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c  end of the BLOB,
357b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
357c0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
357d0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72  nd no data is wr
357e0 69 74 74 65 6e 2e 20 20 5e 49 66 20 4e 20 69 73  itten.  ^If N is
357f0 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65  .** less than ze
35800 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ro [SQLITE_ERROR
35810 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
35820 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
35830 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 7a  tten..** The siz
35840 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 61  e of the BLOB (a
35850 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78  nd hence the max
35860 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b  imum value of N+
35870 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20  iOffset).** can 
35880 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
35890 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
358a0 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
358b0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
358c0 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77  ^An attempt to w
358d0 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72  rite to an expir
358e0 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  ed [BLOB handle]
358f0 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
35900 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20  * error code of 
35910 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20  [SQLITE_ABORT]. 
35920 20 5e 57 72 69 74 65 73 20 74 6f 20 74 68 65 20   ^Writes to the 
35930 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72  BLOB that occurr
35940 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  ed.** before the
35950 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65   [BLOB handle] e
35960 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72  xpired are not r
35970 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68  olled back by th
35980 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20  e.** expiration 
35990 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74  of the handle, t
359a0 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
359b0 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69  those changes mi
359c0 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e  ght.** have been
359d0 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
359e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
359f0 61 74 20 65 78 70 69 72 65 64 20 74 68 65 20 42  at expired the B
35a00 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72  LOB handle.** or
35a10 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65   by other indepe
35a20 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73  ndent statements
35a30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63  ..**.** ^(On suc
35a40 63 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c  cess, sqlite3_bl
35a50 6f 62 5f 77 72 69 74 65 28 29 20 72 65 74 75 72  ob_write() retur
35a60 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a  ns SQLITE_OK..**
35a70 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 20   Otherwise, an  
35a80 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
35a90 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  an [extended err
35aa0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
35ab0 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  rned.)^.**.** Th
35ac0 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
35ad0 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42  works on a [BLOB
35ae0 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68   handle] which h
35af0 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a  as been created.
35b00 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75  ** by a prior su
35b10 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
35b20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
35b30 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68  pen()] and which
35b40 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e   has not.** been
35b50 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69   closed by [sqli
35b60 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
35b70 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20  ].  Passing any 
35b80 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e  other pointer in
35b90 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74  .** to this rout
35ba0 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ine results in u
35bb0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
35bc0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
35bd0 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  e behavior..**.*
35be0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
35bf0 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
35c00 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
35c10 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c  3_blob_write(sql
35c20 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e  ite3_blob *, con
35c30 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20  st void *z, int 
35c40 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  n, int iOffset);
35c50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35c60 3a 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53  : Virtual File S
35c70 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a  ystem Objects.**
35c80 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69  .** A virtual fi
35c90 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 69  lesystem (VFS) i
35ca0 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  s an [sqlite3_vf
35cb0 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61  s] object.** tha
35cc0 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f  t SQLite uses to
35cd0 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74   interact.** wit
35ce0 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  h the underlying
35cf0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
35d00 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 65 20  m.  Most SQLite 
35d10 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68  builds come with
35d20 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66   a.** single def
35d30 61 75 6c 74 20 56 46 53 20 74 68 61 74 20 69 73  ault VFS that is
35d40 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
35d50 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74   the host comput
35d60 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73  er..** New VFSes
35d70 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
35d80 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67 20  ed and existing 
35d90 56 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e 72  VFSes can be unr
35da0 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68  egistered..** Th
35db0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  e following inte
35dc0 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
35dd0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ded..**.** ^The 
35de0 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
35df0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
35e00 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
35e10 6f 20 61 20 56 46 53 20 67 69 76 65 6e 20 69 74  o a VFS given it
35e20 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4e 61 6d 65  s name..** ^Name
35e30 73 20 61 72 65 20 63 61 73 65 20 73 65 6e 73 69  s are case sensi
35e40 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20  tive..** ^Names 
35e50 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
35e60 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
35e70 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 72 65 20  s..** ^If there 
35e80 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e  is no match, a N
35e90 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
35ea0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
35eb0 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c  zVfsName is NULL
35ec0 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
35ed0 74 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65  t VFS is returne
35ee0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65 77 20 56 46  d..**.** ^New VF
35ef0 53 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72  Ses are register
35f00 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f  ed with sqlite3_
35f10 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a  vfs_register()..
35f20 2a 2a 20 5e 45 61 63 68 20 6e 65 77 20 56 46 53  ** ^Each new VFS
35f30 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66   becomes the def
35f40 61 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20  ault VFS if the 
35f50 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73  makeDflt flag is
35f60 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 61   set..** ^The sa
35f70 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65  me VFS can be re
35f80 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
35f90 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20  e times without 
35fa0 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e 54 6f 20 6d  injury..** ^To m
35fb0 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20  ake an existing 
35fc0 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66  VFS into the def
35fd0 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74  ault VFS, regist
35fe0 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77  er it again.** w
35ff0 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74  ith the makeDflt
36000 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74   flag set.  If t
36010 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46 53  wo different VFS
36020 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73  es with the.** s
36030 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67  ame name are reg
36040 69 73 74 65 72 65 64 2c 20 74 68 65 20 62 65 68  istered, the beh
36050 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
36060 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53  ed.  If a.** VFS
36070 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77   is registered w
36080 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20  ith a name that 
36090 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d  is NULL or an em
360a0 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74  pty string,.** t
360b0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
360c0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
360d0 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69 73 74 65 72  *.** ^Unregister
360e0 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65 20   a VFS with the 
360f0 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
36100 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 61  gister() interfa
36110 63 65 2e 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  ce..** ^(If the 
36120 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75  default VFS is u
36130 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f  nregistered, ano
36140 74 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73  ther VFS is chos
36150 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66  en as.** the def
36160 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63  ault.  The choic
36170 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46  e for the new VF
36180 53 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 29  S is arbitrary.)
36190 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73  ^.*/.sqlite3_vfs
361a0 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   *sqlite3_vfs_fi
361b0 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  nd(const char *z
361c0 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71  VfsName);.int sq
361d0 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
361e0 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  er(sqlite3_vfs*,
361f0 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a   int makeDflt);.
36200 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  int sqlite3_vfs_
36210 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69 74  unregister(sqlit
36220 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e3_vfs*);../*.**
36230 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
36240 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  es.**.** The SQL
36250 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
36260 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
36270 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68   thread.** synch
36280 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f 75  ronization. Thou
36290 67 68 20 74 68 65 79 20 61 72 65 20 69 6e 74 65  gh they are inte
362a0 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61  nded for interna
362b0 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69  l.** use by SQLi
362c0 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69  te, code that li
362d0 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69  nks against SQLi
362e0 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74  te is.** permitt
362f0 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66  ed to use any of
36300 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
36310 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
36320 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f  e source code co
36330 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20  ntains multiple 
36340 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
36350 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65  ** of these mute
36360 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20  x routines.  An 
36370 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c  appropriate impl
36380 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
36390 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61   selected automa
363a0 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69  tically at compi
363b0 6c 65 2d 74 69 6d 65 2e 20 20 5e 28 54 68 65 20  le-time.  ^(The 
363c0 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70  following.** imp
363d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65  lementations are
363e0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
363f0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a  e SQLite core:.*
36400 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
36410 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
36420 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  _OS2.** <li>   S
36430 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52  QLITE_MUTEX_PTHR
36440 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  EAD.** <li>   SQ
36450 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a  LITE_MUTEX_W32.*
36460 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
36470 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f  MUTEX_NOOP.** </
36480 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ul>)^.**.** ^The
36490 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f   SQLITE_MUTEX_NO
364a0 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  OP implementatio
364b0 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f  n is a set of ro
364c0 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20 64  utines.** that d
364d0 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b  oes no real lock
364e0 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f  ing and is appro
364f0 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69  priate for use i
36500 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68  n.** a single-th
36510 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
36520 6f 6e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  on.  ^The SQLITE
36530 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53  _MUTEX_OS2,.** S
36540 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52  QLITE_MUTEX_PTHR
36550 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f  EAD, and SQLITE_
36560 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d  MUTEX_W32 implem
36570 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  entations.** are
36580 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
36590 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e   use on OS/2, Un
365a0 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e  ix, and Windows.
365b0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
365c0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
365d0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d  ith the SQLITE_M
365e0 55 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70  UTEX_APPDEF prep
365f0 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72  rocessor.** macr
36600 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20  o defined (with 
36610 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  "-DSQLITE_MUTEX_
36620 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e  APPDEF=1"), then
36630 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70   no mutex.** imp
36640 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69  lementation is i
36650 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65  ncluded with the
36660 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69   library. In thi
36670 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70  s case the.** ap
36680 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
36690 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d  upply a custom m
366a0 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
366b0 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ion using the.**
366c0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
366d0 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66  MUTEX] option of
366e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   the sqlite3_con
366f0 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  fig() function.*
36700 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67  * before calling
36710 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
36720 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68  ize() or any oth
36730 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65  er public sqlite
36740 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  3_.** function t
36750 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  hat calls sqlite
36760 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 29  3_initialize().)
36770 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
36780 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
36790 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63  () routine alloc
367a0 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75  ates a new.** mu
367b0 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20  tex and returns 
367c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
367d0 20 5e 49 66 20 69 74 20 72 65 74 75 72 6e 73 20   ^If it returns 
367e0 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61  NULL.** that mea
367f0 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20  ns that a mutex 
36800 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c  could not be all
36810 6f 63 61 74 65 64 2e 20 20 5e 53 51 4c 69 74 65  ocated.  ^SQLite
36820 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20  .** will unwind 
36830 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65  its stack and re
36840 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 20  turn an error.  
36850 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ^(The argument.*
36860 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  * to sqlite3_mut
36870 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e  ex_alloc() is on
36880 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
36890 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a  er constants:.**
368a0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
368b0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46    SQLITE_MUTEX_F
368c0 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  AST.** <li>  SQL
368d0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
368e0 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
368f0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
36900 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20  _MASTER.** <li> 
36910 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
36920 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e  ATIC_MEM.** <li>
36930 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
36940 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c  TATIC_MEM2.** <l
36950 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
36960 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20  _STATIC_PRNG.** 
36970 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
36980 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a  EX_STATIC_LRU.**
36990 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
369a0 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a  TEX_STATIC_LRU2.
369b0 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
369c0 20 5e 54 68 65 20 66 69 72 73 74 20 74 77 6f 20   ^The first two 
369d0 63 6f 6e 73 74 61 6e 74 73 20 28 53 51 4c 49 54  constants (SQLIT
369e0 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 61 6e 64  E_MUTEX_FAST and
369f0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
36a00 43 55 52 53 49 56 45 29 0a 2a 2a 20 63 61 75 73  CURSIVE).** caus
36a10 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
36a20 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74  alloc() to creat
36a30 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78  e.** a new mutex
36a40 2e 20 20 5e 54 68 65 20 6e 65 77 20 6d 75 74 65  .  ^The new mute
36a50 78 20 69 73 20 72 65 63 75 72 73 69 76 65 20 77  x is recursive w
36a60 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  hen SQLITE_MUTEX
36a70 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73  _RECURSIVE.** is
36a80 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65   used but not ne
36a90 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65  cessarily so whe
36aa0 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  n SQLITE_MUTEX_F
36ab0 41 53 54 20 69 73 20 75 73 65 64 2e 0a 2a 2a 20  AST is used..** 
36ac0 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  The mutex implem
36ad0 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  entation does no
36ae0 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20 61  t need to make a
36af0 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
36b00 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d  between SQLITE_M
36b10 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 61  UTEX_RECURSIVE a
36b20 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  nd SQLITE_MUTEX_
36b30 46 41 53 54 20 69 66 20 69 74 20 64 6f 65 73 0a  FAST if it does.
36b40 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20  ** not want to. 
36b50 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e   ^SQLite will on
36b60 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63  ly request a rec
36b70 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a  ursive mutex in.
36b80 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69  ** cases where i
36b90 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f  t really needs o
36ba0 6e 65 2e 20 20 5e 49 66 20 61 20 66 61 73 74 65  ne.  ^If a faste
36bb0 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20  r non-recursive 
36bc0 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65  mutex.** impleme
36bd0 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  ntation is avail
36be0 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74  able on the host
36bf0 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d   platform, the m
36c00 75 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a  utex subsystem.*
36c10 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73  * might return s
36c20 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72  uch a mutex in r
36c30 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54  esponse to SQLIT
36c40 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a  E_MUTEX_FAST..**
36c50 0a 2a 2a 20 5e 54 68 65 20 6f 74 68 65 72 20 61  .** ^The other a
36c60 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72  llowed parameter
36c70 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  s to sqlite3_mut
36c80 65 78 5f 61 6c 6c 6f 63 28 29 20 28 61 6e 79 74  ex_alloc() (anyt
36c90 68 69 6e 67 20 6f 74 68 65 72 0a 2a 2a 20 74 68  hing other.** th
36ca0 61 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  an SQLITE_MUTEX_
36cb0 46 41 53 54 20 61 6e 64 20 53 51 4c 49 54 45 5f  FAST and SQLITE_
36cc0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29  MUTEX_RECURSIVE)
36cd0 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20   each return.** 
36ce0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
36cf0 74 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e  tatic preexistin
36d00 67 20 6d 75 74 65 78 2e 20 20 5e 53 69 78 20 73  g mutex.  ^Six s
36d10 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
36d20 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65  e.** used by the
36d30 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e   current version
36d40 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74   of SQLite.  Fut
36d50 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
36d60 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64  SQLite.** may ad
36d70 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61  d additional sta
36d80 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74  tic mutexes.  St
36d90 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65  atic mutexes are
36da0 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
36db0 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f   use by SQLite o
36dc0 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
36dd0 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69  ns that use SQLi
36de0 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  te mutexes shoul
36df0 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68  d.** use only th
36e00 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65  e dynamic mutexe
36e10 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  s returned by SQ
36e20 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
36e30 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  or.** SQLITE_MUT
36e40 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a  EX_RECURSIVE..**
36e50 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 69  .** ^Note that i
36e60 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e  f one of the dyn
36e70 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d  amic mutex param
36e80 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55  eters (SQLITE_MU
36e90 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53  TEX_FAST.** or S
36ea0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
36eb0 52 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74  RSIVE) is used t
36ec0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  hen sqlite3_mute
36ed0 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74  x_alloc().** ret
36ee0 75 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74  urns a different
36ef0 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20   mutex on every 
36f00 63 61 6c 6c 2e 20 20 5e 42 75 74 20 66 6f 72 20  call.  ^But for 
36f10 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75  the static.** mu
36f20 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73  tex types, the s
36f30 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74  ame mutex is ret
36f40 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63  urned on every c
36f50 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  all that has.** 
36f60 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75  the same type nu
36f70 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
36f80 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66   sqlite3_mutex_f
36f90 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65  ree() routine de
36fa0 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76  allocates a prev
36fb0 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61  iously.** alloca
36fc0 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  ted dynamic mute
36fd0 78 2e 20 20 5e 53 51 4c 69 74 65 20 69 73 20 63  x.  ^SQLite is c
36fe0 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f  areful to deallo
36ff0 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79  cate every.** dy
37000 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74  namic mutex that
37010 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 20   it allocates.  
37020 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  The dynamic mute
37030 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  xes must not be 
37040 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74  in.** use when t
37050 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  hey are dealloca
37060 74 65 64 2e 20 20 41 74 74 65 6d 70 74 69 6e 67  ted.  Attempting
37070 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61   to deallocate a
37080 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78   static.** mutex
37090 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
370a0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20  fined behavior. 
370b0 20 5e 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64   ^SQLite never d
370c0 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20  eallocates.** a 
370d0 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
370e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
370f0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61  _mutex_enter() a
37100 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nd sqlite3_mutex
37110 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20  _try() routines 
37120 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e  attempt.** to en
37130 74 65 72 20 61 20 6d 75 74 65 78 2e 20 20 5e 49  ter a mutex.  ^I
37140 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
37150 20 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68   is already with
37160 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a  in the mutex,.**
37170 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
37180 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63  nter() will bloc
37190 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75  k and sqlite3_mu
371a0 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72  tex_try() will r
371b0 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
371c0 42 55 53 59 2e 20 20 5e 54 68 65 20 73 71 6c 69  BUSY.  ^The sqli
371d0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
371e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
371f0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a  s [SQLITE_OK].**
37200 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c   upon successful
37210 20 65 6e 74 72 79 2e 20 20 5e 28 4d 75 74 65 78   entry.  ^(Mutex
37220 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
37230 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
37240 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e 20 62  _RECURSIVE can b
37250 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70  e entered multip
37260 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68 65 20  le times by the 
37270 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20  same thread..** 
37280 49 6e 20 73 75 63 68 20 63 61 73 65 73 20 74 68  In such cases th
37290 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74  e,.** mutex must
372a0 20 62 65 20 65 78 69 74 65 64 20 61 6e 20 65 71   be exited an eq
372b0 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  ual number of ti
372c0 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 68  mes before anoth
372d0 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e  er thread.** can
372e0 20 65 6e 74 65 72 2e 29 5e 20 20 5e 28 49 66 20   enter.)^  ^(If 
372f0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
37300 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61  tries to enter a
37310 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  ny other.** kind
37320 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74   of mutex more t
37330 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65  han once, the be
37340 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
37350 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ned..** SQLite w
37360 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69  ill never exhibi
37370 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69  t.** such behavi
37380 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73  or in its own us
37390 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 29 5e 0a  e of mutexes.)^.
373a0 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65 20 73 79 73  **.** ^(Some sys
373b0 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c  tems (for exampl
373c0 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64  e, Windows 95) d
373d0 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68  o not support th
373e0 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  e operation.** i
373f0 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71  mplemented by sq
37400 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
37410 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73  ).  On those sys
37420 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75  tems, sqlite3_mu
37430 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c  tex_try().** wil
37440 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
37450 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54 68  SQLITE_BUSY.  Th
37460 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e  e SQLite core on
37470 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20  ly ever uses.** 
37480 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
37490 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69  y() as an optimi
374a0 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69  zation so this i
374b0 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68  s acceptable beh
374c0 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  avior.)^.**.** ^
374d0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
374e0 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e  x_leave() routin
374f0 65 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20  e exits a mutex 
37500 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76  that was.** prev
37510 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62  iously entered b
37520 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  y the same threa
37530 64 2e 20 20 20 5e 28 54 68 65 20 62 65 68 61 76  d.   ^(The behav
37540 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
37550 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78  ned if the mutex
37560 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
37570 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65  y entered by the
37580 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  .** calling thre
37590 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72  ad or is not cur
375a0 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64  rently allocated
375b0 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
375c0 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65  * never do eithe
375d0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  r.)^.**.** ^If t
375e0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  he argument to s
375f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
37600 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75  er(), sqlite3_mu
37610 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a  tex_try(), or.**
37620 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c   sqlite3_mutex_l
37630 65 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c 4c  eave() is a NULL
37640 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 61   pointer, then a
37650 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  ll three routine
37660 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20 6e  s.** behave as n
37670 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  o-ops..**.** See
37680 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
37690 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e  mutex_held()] an
376a0 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  d [sqlite3_mutex
376b0 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a  _notheld()]..*/.
376c0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73  sqlite3_mutex *s
376d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
376e0 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  oc(int);.void sq
376f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65  lite3_mutex_free
37700 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
37710 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
37720 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74  utex_enter(sqlit
37730 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
37740 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
37750 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  y(sqlite3_mutex*
37760 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
37770 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69  mutex_leave(sqli
37780 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a  te3_mutex*);../*
37790 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
377a0 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  tex Methods Obje
377b0 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
377c0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
377d0 75 63 74 75 72 65 20 64 65 66 69 6e 65 73 20 74  ucture defines t
377e0 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75  he low-level rou
377f0 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f  tines.** used to
37800 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75 73   allocate and us
37810 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a  e mutexes..**.**
37820 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20 64 65   Usually, the de
37830 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c  fault mutex impl
37840 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76  ementations prov
37850 69 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  ided by SQLite a
37860 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e 74  re.** sufficient
37870 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 75 73  , however the us
37880 65 72 20 68 61 73 20 74 68 65 20 6f 70 74 69 6f  er has the optio
37890 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74 69 6e  n of substitutin
378a0 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d  g a custom.** im
378b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
378c0 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64 65 70   specialized dep
378d0 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79 73 74  loyments or syst
378e0 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20 53 51  ems for which SQ
378f0 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  Lite.** does not
37900 20 70 72 6f 76 69 64 65 20 61 20 73 75 69 74 61   provide a suita
37910 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
37920 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65  on. In this case
37930 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 63 72  , the user.** cr
37940 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75 6c 61  eates and popula
37950 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  tes an instance 
37960 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
37970 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f 20  e to pass.** to 
37980 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
37990 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65 20   along with the 
379a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
379b0 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  UTEX] option..**
379c0 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 61   Additionally, a
379d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
379e0 69 73 20 73 74 72 75 63 74 75 72 65 20 63 61 6e  is structure can
379f0 20 62 65 20 75 73 65 64 20 61 73 20 61 6e 0a 2a   be used as an.*
37a00 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61 62 6c  * output variabl
37a10 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e 67 20  e when querying 
37a20 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72 20 74  the system for t
37a30 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74 65 78  he current mutex
37a40 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
37a50 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20 5b 53  on, using the [S
37a60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
37a70 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a  MUTEX] option..*
37a80 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78  *.** ^The xMutex
37a90 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65 66 69  Init method defi
37aa0 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75  ned by this stru
37ab0 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64  cture is invoked
37ac0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73   as.** part of s
37ad0 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a 61  ystem initializa
37ae0 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71 6c 69  tion by the sqli
37af0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
37b00 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 54   function..** ^T
37b10 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f  he xMutexInit ro
37b20 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 20 62  utine is calle b
37b30 79 20 53 51 4c 69 74 65 20 65 78 61 63 74 6c 79  y SQLite exactly
37b40 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 0a 2a   once for each.*
37b50 2a 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  * effective call
37b60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69   to [sqlite3_ini
37b70 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a  tialize()]..**.*
37b80 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64  * ^The xMutexEnd
37b90 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20   method defined 
37ba0 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72  by this structur
37bb0 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a  e is invoked as.
37bc0 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65  ** part of syste
37bd0 6d 20 73 68 75 74 64 6f 77 6e 20 62 79 20 74 68  m shutdown by th
37be0 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
37bf0 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54  wn() function. T
37c00 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
37c10 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65 74  tion of this met
37c20 68 6f 64 20 69 73 20 65 78 70 65 63 74 65 64 20  hod is expected 
37c30 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f  to release all o
37c40 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65  utstanding.** re
37c50 73 6f 75 72 63 65 73 20 6f 62 74 61 69 6e 65 64  sources obtained
37c60 20 62 79 20 74 68 65 20 6d 75 74 65 78 20 6d 65   by the mutex me
37c70 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61  thods implementa
37c80 74 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79  tion, especially
37c90 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61 69 6e  .** those obtain
37ca0 65 64 20 62 79 20 74 68 65 20 78 4d 75 74 65 78  ed by the xMutex
37cb0 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20 20 5e 54  Init method.  ^T
37cc0 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a  he xMutexEnd().*
37cd0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  * interface is i
37ce0 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f  nvoked exactly o
37cf0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c  nce for each cal
37d00 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68  l to [sqlite3_sh
37d10 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a  utdown()]..**.**
37d20 20 5e 28 54 68 65 20 72 65 6d 61 69 6e 69 6e 67   ^(The remaining
37d30 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64   seven methods d
37d40 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73  efined by this s
37d50 74 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78  tructure (xMutex
37d60 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78  Alloc,.** xMutex
37d70 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65  Free, xMutexEnte
37d80 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d  r, xMutexTry, xM
37d90 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65  utexLeave, xMute
37da0 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75  xHeld and.** xMu
37db0 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c  texNotheld) impl
37dc0 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77  ement the follow
37dd0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28  ing interfaces (
37de0 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a  respectively):.*
37df0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
37e00 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
37e10 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c  tex_alloc()] </l
37e20 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
37e30 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65  qlite3_mutex_fre
37e40 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  e()] </li>.**   
37e50 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
37e60 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f  utex_enter()] </
37e70 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
37e80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
37e90 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  y()] </li>.**   
37ea0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
37eb0 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f  utex_leave()] </
37ec0 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
37ed0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
37ee0 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  ld()] </li>.**  
37ef0 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
37f00 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
37f10 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29   </li>.** </ul>)
37f20 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79  ^.**.** The only
37f30 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 74   difference is t
37f40 68 61 74 20 74 68 65 20 70 75 62 6c 69 63 20 73  hat the public s
37f50 71 6c 69 74 65 33 5f 58 58 58 20 66 75 6e 63 74  qlite3_XXX funct
37f60 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 0a  ions enumerated.
37f70 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c  ** above silentl
37f80 79 20 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76  y ignore any inv
37f90 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 70 61  ocations that pa
37fa0 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ss a NULL pointe
37fb0 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
37fc0 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61  a valid mutex ha
37fd0 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d  ndle. The implem
37fe0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
37ff0 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64   methods defined
38000 0a 2a 2a 20 62 79 20 74 68 69 73 20 73 74 72 75  .** by this stru
38010 63 74 75 72 65 20 61 72 65 20 6e 6f 74 20 72 65  cture are not re
38020 71 75 69 72 65 64 20 74 6f 20 68 61 6e 64 6c 65  quired to handle
38030 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 20   this case, the 
38040 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61  results.** of pa
38050 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
38060 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
38070 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61  a valid mutex ha
38080 6e 64 6c 65 20 61 72 65 20 75 6e 64 65 66 69 6e  ndle are undefin
38090 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69  ed.** (i.e. it i
380a0 73 20 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20  s acceptable to 
380b0 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65  provide an imple
380c0 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 73  mentation that s
380d0 65 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69  egfaults if.** i
380e0 74 20 69 73 20 70 61 73 73 65 64 20 61 20 4e 55  t is passed a NU
380f0 4c 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2a 0a  LL pointer)..**.
38100 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69  ** The xMutexIni
38110 74 28 29 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  t() method must 
38120 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
38130 5e 49 74 20 6d 75 73 74 20 62 65 20 68 61 72 6d  ^It must be harm
38140 6c 65 73 73 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  less to.** invok
38150 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d  e xMutexInit() m
38160 75 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74  utiple times wit
38170 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
38180 63 65 73 73 20 61 6e 64 20 77 69 74 68 6f 75 74  cess and without
38190 0a 2a 2a 20 69 6e 74 65 72 76 65 6e 69 6e 67 20  .** intervening 
381a0 63 61 6c 6c 73 20 74 6f 20 78 4d 75 74 65 78 45  calls to xMutexE
381b0 6e 64 28 29 2e 20 20 53 65 63 6f 6e 64 20 61 6e  nd().  Second an
381c0 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
381d0 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75 74 65 78 49  ls to.** xMutexI
381e0 6e 69 74 28 29 20 6d 75 73 74 20 62 65 20 6e 6f  nit() must be no
381f0 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 78 4d 75  -ops..**.** ^xMu
38200 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 6e  texInit() must n
38210 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65  ot use SQLite me
38220 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
38230 28 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  ([sqlite3_malloc
38240 28 29 5d 0a 2a 2a 20 61 6e 64 20 69 74 73 20 61  ()].** and its a
38250 73 73 6f 63 69 61 74 65 73 29 2e 20 20 5e 53 69  ssociates).  ^Si
38260 6d 69 6c 61 72 6c 79 2c 20 78 4d 75 74 65 78 41  milarly, xMutexA
38270 6c 6c 6f 63 28 29 20 6d 75 73 74 20 6e 6f 74 20  lloc() must not 
38280 75 73 65 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72  use SQLite memor
38290 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
382a0 66 6f 72 20 61 20 73 74 61 74 69 63 20 6d 75 74  for a static mut
382b0 65 78 2e 20 20 5e 48 6f 77 65 76 65 72 20 78 4d  ex.  ^However xM
382c0 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 61 79 20  utexAlloc() may 
382d0 75 73 65 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 65  use SQLite.** me
382e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
382f0 66 6f 72 20 61 20 66 61 73 74 20 6f 72 20 72 65  for a fast or re
38300 63 75 72 73 69 76 65 20 6d 75 74 65 78 2e 0a 2a  cursive mutex..*
38310 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
38320 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 78 4d 75  l invoke the xMu
38330 74 65 78 45 6e 64 28 29 20 6d 65 74 68 6f 64 20  texEnd() method 
38340 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 68  when [sqlite3_sh
38350 75 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a 2a 20  utdown()] is.** 
38360 63 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e 6c 79  called, but only
38370 20 69 66 20 74 68 65 20 70 72 69 6f 72 20 63 61   if the prior ca
38380 6c 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e 69 74  ll to xMutexInit
38390 20 72 65 74 75 72 6e 65 64 20 53 51 4c 49 54 45   returned SQLITE
383a0 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75 74 65  _OK..** If xMute
383b0 78 49 6e 69 74 20 66 61 69 6c 73 20 69 6e 20 61  xInit fails in a
383c0 6e 79 20 77 61 79 2c 20 69 74 20 69 73 20 65 78  ny way, it is ex
383d0 70 65 63 74 65 64 20 74 6f 20 63 6c 65 61 6e 20  pected to clean 
383e0 75 70 20 61 66 74 65 72 20 69 74 73 65 6c 66 0a  up after itself.
383f0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 72 65 74 75  ** prior to retu
38400 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65 64 65  rning..*/.typede
38410 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
38420 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 73  _mutex_methods s
38430 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
38440 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
38450 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
38460 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d 75  ds {.  int (*xMu
38470 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b 0a  texInit)(void);.
38480 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 6e    int (*xMutexEn
38490 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c 69  d)(void);.  sqli
384a0 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d 75  te3_mutex *(*xMu
384b0 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a  texAlloc)(int);.
384c0 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 46    void (*xMutexF
384d0 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  ree)(sqlite3_mut
384e0 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a  ex *);.  void (*
384f0 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 6c  xMutexEnter)(sql
38500 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20  ite3_mutex *);. 
38510 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 79   int (*xMutexTry
38520 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
38530 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75  *);.  void (*xMu
38540 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 65  texLeave)(sqlite
38550 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e  3_mutex *);.  in
38560 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 28  t (*xMutexHeld)(
38570 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
38580 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
38590 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 33  Notheld)(sqlite3
385a0 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f  _mutex *);.};../
385b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
385c0 75 74 65 78 20 56 65 72 69 66 69 63 61 74 69 6f  utex Verificatio
385d0 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
385e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
385f0 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71  ex_held() and sq
38600 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
38610 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a  eld() routines.*
38620 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  * are intended f
38630 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73  or use inside as
38640 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74  sert() statement
38650 73 2e 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20  s.  ^The SQLite 
38660 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73  core.** never us
38670 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  es these routine
38680 73 20 65 78 63 65 70 74 20 69 6e 73 69 64 65 20  s except inside 
38690 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64 20  an assert() and 
386a0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
386b0 61 72 65 20 61 64 76 69 73 65 64 20 74 6f 20 66  are advised to f
386c0 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20 6f  ollow the lead o
386d0 66 20 74 68 65 20 63 6f 72 65 2e 20 20 5e 54 68  f the core.  ^Th
386e0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e  e SQLite core on
386f0 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 69  ly.** provides i
38700 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
38710 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
38720 73 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  s when it is com
38730 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  piled.** with th
38740 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 66  e SQLITE_DEBUG f
38750 6c 61 67 2e 20 20 5e 45 78 74 65 72 6e 61 6c 20  lag.  ^External 
38760 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
38770 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c  tions.** are onl
38780 79 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72  y required to pr
38790 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 74  ovide these rout
387a0 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44  ines if SQLITE_D
387b0 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e  EBUG is.** defin
387c0 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47  ed and if NDEBUG
387d0 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e   is not defined.
387e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
387f0 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 72 65  utines should re
38800 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65  turn true if the
38810 20 6d 75 74 65 78 20 69 6e 20 74 68 65 69 72 20   mutex in their 
38820 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68  argument.** is h
38830 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c  eld or not held,
38840 20 72 65 73 70 65 63 74 69 76 65 6c 79 2c 20 62   respectively, b
38850 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  y the calling th
38860 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  read..**.** ^The
38870 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
38880 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20  is not required 
38890 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72 73  to provided vers
388a0 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ions of these.**
388b0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61   routines that a
388c0 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66  ctually work. If
388d0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
388e0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f