/ Hex Artifact Content
Login

Artifact 14aa9773a255f1dca579218f0981806a3c1b479c:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
42b0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
42c0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
42d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
42e0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
42f0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4300: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4310: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4320: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4330: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4340: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
4350: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4360: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4370: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4380: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
43a0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
43b0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
43c0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
43d0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
43e0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
43f0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4400: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4420: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4430: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4440: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4460: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4470: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4480: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4490: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
44a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
44b0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
44c0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
44d0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
44e0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
44f0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4500: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4510: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4530: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4540: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4550: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4560: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4580: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4590: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
45a0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
45b0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
45c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
45d0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
45e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
45f0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4600: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4610: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4620: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4630: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4640: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4650: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4660: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4670: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4680: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4690: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
46a0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
46b0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
46c0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
46d0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
46e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4700: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
4710: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4720: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4730: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4740: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
4750: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
4760: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
4770: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4780: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4790: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
47a0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
47b0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
47c0: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
47d0: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
47e0: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
47f0: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4800: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4810: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4820: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4830: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4840: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4850: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4860: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4870: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
4880: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
4890: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
48a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
48b0: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
48c0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
48d0: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
48e0: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
48f0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4900: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4910: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4920: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4930: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4940: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4950: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4960: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4970: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
4980: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
4990: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
49a0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
49b0: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
49c0: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
49d0: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
49e0: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
49f0: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
4a00: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
4a10: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
4a20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4a30: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
4a40: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
4a50: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
4a60: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
4a70: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
4a80: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
4a90: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
4aa0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
4ab0: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
4ac0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
4ad0: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
4ae0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
4af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
4b00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4b10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4b30: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
4b70: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
4bf0: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
4d50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d60: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
4d70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d80: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
4d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4da0: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
4db0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4dc0: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
4dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4de0: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
4df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e00: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
4e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e20: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
4e30: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
4e40: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
4e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e60: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
4e70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e80: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
4e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ea0: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
4eb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4ec0: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
4ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ee0: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
4ef0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4f00: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
4f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4f20: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
4f30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
4f40: 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a  KED | (1<<8) )..
4f50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4f60: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
4f70: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
4f80: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
4f90: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
4fa0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
4fb0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
4fc0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
4fd0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
4fe0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
4ff0: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
5000: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ter to the xOpen
5010: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a   method of the.*
5020: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
5030: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
5040: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5050: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5060: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
5070: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5080: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5090: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
50a0: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
50b0: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
50c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
50d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
50f0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
5100: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
5110: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5120: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
5140: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
5150: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
5160: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
5180: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
5190: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
51a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
51c0: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
51d0: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
51e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5200: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
5210: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
5220: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5240: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
5250: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
5260: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5280: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
5290: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
52a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
52c0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
52d0: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
52e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5300: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
5310: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
5320: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5340: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
5350: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
5360: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5380: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
5390: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
53a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
53c0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
53d0: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
53e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
53f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
5410: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
5420: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
5430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5460: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5470: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
5480: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5490: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
54b0: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
54c0: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
54d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
54e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a  en_v2() */../*.*
54f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
5500: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
5510: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
5520: 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73  viceCapabilities
5530: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
5540: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5550: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
5560: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
5570: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
5580: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a  or of the these.
5590: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
55a0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
55b0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
55c0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
55d0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
55e0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
55f0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
5600: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5610: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
5620: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5630: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
5640: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
5650: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
5660: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
5670: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5680: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
5690: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
56a0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
56b0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
56c0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
56d0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
56e0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
56f0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
5700: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
5710: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
5720: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5730: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5740: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
5750: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
5760: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
5770: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
5780: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
5790: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
57a0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
57b0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
57c0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
57d0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
57e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
57f0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
5800: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
5810: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
5820: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
5830: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
5840: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
5850: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5870: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
5880: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5890: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58a0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
58b0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
58c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58d0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
58e0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
58f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5900: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
5910: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5930: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5940: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5960: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5970: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5990: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
59a0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
59b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59c0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
59d0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59f0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5a00: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a20: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
5a30: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a50: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
5a60: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
5a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5a80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5a90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5aa0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5ab0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5ac0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5ad0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ae0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5af0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5b00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5b10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5b30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5b60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5b70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5b90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5ba0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5bb0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5bc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5bd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5be0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5bf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5c00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5c10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5c20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5c30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5c40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5c50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5c60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5c70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5c80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5c90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ca0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5cb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5cc0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5cd0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ce0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5cf0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5d00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5d10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5d20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5d30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5d40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5d50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5d60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5d70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5d80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5d90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5da0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5db0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5dc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5de0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5df0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
5e00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
5e10: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
5e20: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
5e30: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5e50: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
5e60: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
5e70: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
5e80: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
5e90: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
5ea0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5eb0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
5ec0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
5ed0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5ee0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
5ef0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
5f00: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
5f10: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
5f20: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
5f30: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
5f40: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
5f50: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
5f60: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
5f70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
5f80: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
5f90: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
5fa0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
5fb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
5fc0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
5fd0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
5fe0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
5ff0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6000: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6010: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6020: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6030: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6040: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6050: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6060: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6070: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6080: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6090: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
60a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
60b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
60c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
60d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
60e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
60f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6100: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6110: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6120: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6130: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6140: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6150: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6160: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6170: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6180: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6190: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
61a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
61b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
61c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
61d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
61e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
61f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6200: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6210: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6220: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6230: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6240: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6250: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6260: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6270: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6280: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6290: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
62a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
62b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
62c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
62d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
62e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
62f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6300: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6310: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6320: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6330: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6340: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6350: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6360: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6370: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6380: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6390: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
63a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
63b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
63c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
63d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
63e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
63f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6400: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6410: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6420: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6430: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6440: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6450: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6460: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6470: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6480: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6490: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
64a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
64b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
64c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
64d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
64e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
64f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6500: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6510: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6520: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6530: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6540: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6550: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6560: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6570: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6580: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6590: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
65a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
65c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
65e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
65f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6600: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6610: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6620: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6630: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6640: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6650: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6660: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6670: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6680: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6690: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
66a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
66b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
66c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
66d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
66e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
66f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6700: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6710: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6720: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6730: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6740: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6750: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6760: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6770: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6780: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6790: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
67a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
67b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
67c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
67d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
67e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
67f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6800: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6810: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6820: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6830: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6840: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6850: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6860: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6870: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6880: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6890: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
68a0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
68b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
68c0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
68d0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
68e0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
68f0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6900: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6910: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6920: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6930: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6940: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6950: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6960: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6970: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6980: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6990: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
69a0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
69b0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
69c0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
69d0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
69e0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
69f0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6a00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6a10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6a20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6a30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6a40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6a50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6a60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6a70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6a80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6a90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6aa0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6ac0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6ad0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ae0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6af0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6b00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6b10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6b20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6b30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6b40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6b50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6b60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6b70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6b80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6b90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6ba0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6bb0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6bc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6bd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6be0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6bf0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6c00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6c10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6c20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6c30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6c40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6c60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6c80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ca0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6cc0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cd0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ce0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6d00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6d10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6d20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6d30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6d40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6d50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6d60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6d70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6d80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6d90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6da0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6db0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6dc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6dd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6de0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6df0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6e00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6e10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6e20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6e30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6e40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6e50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6e60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6e70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6e80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6e90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
6ea0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
6eb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
6ec0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
6ed0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
6ee0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6ef0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6f00: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6f10: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6f20: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6f40: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6f50: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6f60: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6f70: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6f80: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
6f90: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
6fa0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
6fb0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
6fc0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
6fd0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
6fe0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
6ff0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7000: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7010: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7020: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7030: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7040: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7050: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7060: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7070: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7080: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7090: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
70a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
70b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
70c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
70d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
70e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
70f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7100: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7110: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7120: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7130: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7140: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7150: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7160: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7170: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7180: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7190: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
71a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
71b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
71c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
71d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
71e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
71f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7200: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7210: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7220: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7230: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7240: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7250: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7260: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7270: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7280: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7290: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
72a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
72b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
72c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
72d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
72f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7300: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7310: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7320: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7330: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7340: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7350: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7360: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7370: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7380: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7390: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
73a0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
73b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4f 70 65 6e    int (*xShmOpen
73c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
73d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 53 69  ;.  int (*xShmSi
73e0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
73f0: 2a 2c 20 69 6e 74 20 72 65 71 53 69 7a 65 2c 20  *, int reqSize, 
7400: 69 6e 74 20 2a 70 4e 65 77 53 69 7a 65 29 3b 0a  int *pNewSize);.
7410: 20 20 69 6e 74 20 28 2a 78 53 68 6d 47 65 74 29    int (*xShmGet)
7420: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7430: 69 6e 74 20 72 65 71 53 69 7a 65 2c 20 69 6e 74  int reqSize, int
7440: 20 2a 70 53 69 7a 65 2c 20 76 6f 69 64 2a 2a 29   *pSize, void**)
7450: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 52 65  ;.  int (*xShmRe
7460: 6c 65 61 73 65 29 28 73 71 6c 69 74 65 33 5f 66  lease)(sqlite3_f
7470: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
7480: 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  ShmLock)(sqlite3
7490: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 73 69  _file*, int desi
74a0: 72 65 64 4c 6f 63 6b 2c 20 69 6e 74 20 2a 67 6f  redLock, int *go
74b0: 74 4c 6f 63 6b 29 3b 0a 20 20 69 6e 74 20 28 2a  tLock);.  int (*
74c0: 78 53 68 6d 43 6c 6f 73 65 29 28 73 71 6c 69 74  xShmClose)(sqlit
74d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
74e0: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
74f0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
7500: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
7510: 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 2 */.  /* Ad
7520: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
7530: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
7540: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
7550: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
7560: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
7570: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
7580: 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  codes.**.** Thes
7590: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
75a0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
75b0: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
75c0: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
75d0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
75e0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
75f0: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
7600: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
7610: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
7620: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ace..**.** The [
7630: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
7640: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
7650: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
7660: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
7670: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
7680: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7690: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
76a0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
76b0: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
76c0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
76d0: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
76e0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
76f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
7700: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
7710: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
7720: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
7730: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
7740: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
7750: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
7760: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
7770: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
7780: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
7790: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
77a0: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
77b0: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
77c0: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  n SQLITE_TEST.**
77d0: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a   is defined..*/.
77e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
77f0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
7800: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
7810: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
7820: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a  ROXYFILE      2.
7830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7840: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
7850: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
7860: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
7870: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a  O             4.
7880: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7890: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
78a0: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
78b0: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
78c0: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
78d0: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
78e0: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
78f0: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
7900: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
7910: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
7920: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
7930: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
7940: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
7950: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
7960: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
7970: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
7980: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
7990: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
79a0: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
79b0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
79c0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
79d0: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
79e0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
79f0: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
7a00: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
7a10: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7a20: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
7a30: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
7a40: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
7a50: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
7a60: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
7a70: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
7a80: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
7a90: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
7aa0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
7ab0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
7ac0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
7ad0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
7ae0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
7af0: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stem"..**.** The
7b00: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
7b10: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
7b20: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
7b30: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
7b40: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
7b50: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
7b60: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
7b70: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
7b80: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
7b90: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
7ba0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
7bb0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
7bc0: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
7bd0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
7be0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
7bf0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
7c00: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
7c10: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
7c20: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
7c30: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
7c40: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
7c50: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
7c60: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
7c70: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
7c80: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
7c90: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
7ca0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
7cb0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
7cc0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
7cd0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
7ce0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
7cf0: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
7d00: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
7d10: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
7d20: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
7d30: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
7d40: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
7d50: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
7d60: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
7d70: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
7d80: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
7d90: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
7da0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
7db0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
7dc0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
7dd0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
7de0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
7df0: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
7e00: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
7e10: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
7e20: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
7e30: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
7e40: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
7e50: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
7e60: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
7e70: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
7e80: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
7e90: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
7ea0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
7eb0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
7ec0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
7ed0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
7ee0: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
7ef0: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
7f00: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
7f10: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
7f20: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
7f30: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
7f40: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
7f50: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
7f60: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
7f70: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
7f80: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
7f90: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
7fa0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
7fb0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
7fc0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
7fd0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
7fe0: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
7ff0: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
8000: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
8010: 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  es..**.** SQLite
8020: 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20   will guarantee 
8030: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
8040: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
8050: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
8060: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
8070: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
8080: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
8090: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53  llPathname().  S
80a0: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
80b0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
80c0: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
80d0: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
80e0: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
80f0: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
8100: 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20  led. Because of 
8110: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
8120: 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tence,.** the [s
8130: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
8140: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
8150: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
8160: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
8170: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
8180: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
8190: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
81a0: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
81b0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
81c0: 73 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  s xOpen is a NUL
81d0: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
81e0: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
81f0: 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ent its own temp
8200: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
8210: 68 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76  he file.  Whenev
8220: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
8230: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
8240: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
8250: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
8260: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
8270: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
8280: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
8290: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
82a0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
82b0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
82c0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
82d0: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
82e0: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
82f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
8300: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
8310: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
8320: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
8330: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
8340: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
8350: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
8360: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
8370: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
8380: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
8390: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
83a0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
83b0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
83c0: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
83d0: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
83e0: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
83f0: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
8400: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
8410: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
8420: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  set..**.** SQLit
8430: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
8440: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
8450: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
8460: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
8470: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
8480: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
8490: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
84a0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
84b0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
84c0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
84d0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
84e0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
84f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
8500: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
8510: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
8520: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
8530: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8540: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
8550: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
8560: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
8570: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8580: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
8590: 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  RNAL].** </ul>.*
85a0: 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
85b0: 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
85c0: 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
85d0: 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
85e0: 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  o.** change the 
85f0: 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
8600: 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
8610: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
8620: 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
8630: 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
8640: 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
8650: 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67   or rollback mig
8660: 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f  ht make.** the o
8670: 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c  pen of a journal
8680: 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20   file a no-op.  
8690: 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a  Writes to this j
86a0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20  ournal would.** 
86b0: 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20  also be no-ops, 
86c0: 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20  and any attempt 
86d0: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
86e0: 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  nal would return
86f0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  .** SQLITE_IOERR
8700: 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  .  Or the implem
8710: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
8720: 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20  ecognize that a 
8730: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
8740: 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70   will be doing p
8750: 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
8760: 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
8770: 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a  tes in a random.
8780: 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74  ** order and set
8790: 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
87a0: 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
87b0: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
87c0: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
87d0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
87e0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
87f0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a   xOpen method:.*
8800: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8810: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  > [SQLITE_OPEN_D
8820: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
8830: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
8840: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a  EN_EXCLUSIVE].**
8850: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
8860: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
8870: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
8880: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
8890: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
88a0: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
88b0: 20 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b 53   closed.  The [S
88c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
88d0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
88e0: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
88f0: 50 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f  P  databases, jo
8900: 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73  urnals and for s
8910: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
8920: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
8930: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
8940: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
8950: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
8960: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
8970: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
8980: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
8990: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
89a0: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
89b0: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
89c0: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
89d0: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
89e0: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
89f0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
8a00: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
8a10: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
8a20: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
8a30: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
8a40: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
8a50: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
8a60: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
8a70: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
8a80: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
8a90: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
8aa0: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
8ab0: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
8ac0: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
8ad0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
8ae0: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
8af0: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 41   access..**.** A
8b00: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
8b10: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
8b20: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
8b30: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
8b40: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
8b50: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
8b60: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
8b70: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
8b80: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
8b90: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
8ba0: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
8bb0: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
8bc0: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
8bd0: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
8be0: 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a   in.  Note that.
8bf0: 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  ** the xOpen met
8c00: 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65  hod must set the
8c10: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
8c20: 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72  ethods to either
8c30: 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c  .** a valid [sql
8c40: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
8c50: 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55   object or to NU
8c60: 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20  LL.  xOpen must 
8c70: 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20  do.** this even 
8c80: 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
8c90: 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63  s.  SQLite expec
8ca0: 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69  ts that the sqli
8cb0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
8cc0: 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c  s.** element wil
8cd0: 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72  l be valid after
8ce0: 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72   xOpen returns r
8cf0: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
8d00: 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66   success.** or f
8d10: 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f  ailure of the xO
8d20: 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  pen call..**.** 
8d30: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
8d40: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
8d50: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
8d60: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
8d70: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
8d80: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
8d90: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
8da0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
8db0: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
8dc0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
8dd0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
8de0: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
8df0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
8e00: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
8e10: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
8e20: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
8e30: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
8e40: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
8e50: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
8e60: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
8e70: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
8e80: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
8e90: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
8ea0: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
8eb0: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
8ec0: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
8ed0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
8ee0: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
8ef0: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
8f00: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
8f10: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
8f20: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
8f30: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
8f40: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
8f50: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
8f60: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
8f70: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
8f80: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
8f90: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
8fa0: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
8fb0: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
8fc0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
8fd0: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
8fe0: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
8ff0: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
9000: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
9010: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
9020: 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  ep(), and xCurre
9030: 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61  ntTime() interfa
9040: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73  ces.** are not s
9050: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
9060: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
9070: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
9080: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
9090: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
90a0: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
90b0: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
90c0: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
90d0: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
90e0: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
90f0: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
9100: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
9110: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
9120: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
9130: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
9140: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
9150: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
9160: 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65  ed..** The xSlee
9170: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
9180: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  s the calling th
9190: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
91a0: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
91b0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
91c0: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
91d0: 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   The xCurrentTim
91e0: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
91f0: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
9200: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
9210: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
9220: 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74  nd time..**.*/.t
9230: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
9240: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
9250: 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71  3_vfs;.struct sq
9260: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
9270: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
9280: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
9290: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
92a0: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 32 29  er (currently 2)
92b0: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
92c0: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
92d0: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
92e0: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
92f0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
9300: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
9310: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
9320: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
9330: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
9340: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
9350: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
9360: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
9370: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
9380: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
9390: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
93a0: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
93b0: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
93c0: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
93d0: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
93e0: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
93f0: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
9400: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
9410: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
9420: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
9430: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
9440: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
9450: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
9460: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
9470: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
9480: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
9490: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
94a0: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
94b0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
94c0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
94d0: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
94e0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
94f0: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
9500: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
9510: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
9520: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
9530: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
9540: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
9550: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9560: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
9570: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
9580: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
9590: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
95a0: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
95b0: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
95c0: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
95d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
95e0: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
95f0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
9600: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
9610: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
9620: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
9630: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
9640: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
9650: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
9660: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9670: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
9680: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
9690: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
96a0: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
96b0: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
96c0: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
96d0: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
96e0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
96f0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
9700: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
9710: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
9720: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
9730: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
9740: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
9750: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
9760: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
9770: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61  */.  int (*xRena
9780: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
9790: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  , const char *zO
97a0: 6c 64 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ld, const char *
97b0: 7a 4e 65 77 2c 20 69 6e 74 20 64 69 72 53 79 6e  zNew, int dirSyn
97c0: 63 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  c);.  int (*xCur
97d0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
97e0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
97f0: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
9800: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
9810: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
9820: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
9830: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
9840: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
9850: 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
9860: 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
9870: 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
9880: 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
9890: 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
98a0: 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
98b0: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a   this happens. .
98c0: 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43    */.};../*.** C
98d0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
98e0: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
98f0: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
9900: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
9910: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
9920: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
9930: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
9940: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
9950: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
9960: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
9970: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
9980: 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
9990: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
99a0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
99b0: 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a  s looking for..*
99c0: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
99d0: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
99e0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
99f0: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
9a00: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
9a10: 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74  e exists..** Wit
9a20: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
9a30: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
9a40: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
9a50: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
9a60: 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68  the file is both
9a70: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
9a80: 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 68 20  itable..** With 
9a90: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
9aa0: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
9ab0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
9ac0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
9ad0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a  e is readable..*
9ae0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9af0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
9b00: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
9b10: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
9b20: 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ITE 1.#define SQ
9b30: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
9b40: 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43        2../*.** C
9b50: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
9b60: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
9b70: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
9b80: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
9b90: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
9ba0: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
9bb0: 69 6e 67 20 73 74 61 74 65 73 20 74 68 61 74 0a  ing states that.
9bc0: 2a 2a 20 61 6e 20 73 71 6c 69 74 65 33 5f 73 68  ** an sqlite3_sh
9bd0: 6d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  m object can be 
9be0: 69 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  in..*/.#define S
9bf0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
9c00: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
9c10: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 52 45 41 44   SQLITE_SHM_READ
9c20: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
9c30: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 52 45  ne SQLITE_SHM_RE
9c40: 41 44 5f 46 55 4c 4c 20 20 20 20 32 0a 23 64 65  AD_FULL    2.#de
9c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
9c60: 57 52 49 54 45 20 20 20 20 20 20 20 20 33 0a 23  WRITE        3.#
9c70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
9c80: 4d 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 34  M_PENDING      4
9c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9ca0: 53 48 4d 5f 43 48 45 43 4b 50 4f 49 4e 54 20 20  SHM_CHECKPOINT  
9cb0: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
9cc0: 45 5f 53 48 4d 5f 52 45 43 4f 56 45 52 20 20 20  E_SHM_RECOVER   
9cd0: 20 20 20 36 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     6../*.** CAPI
9ce0: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
9cf0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
9d00: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
9d10: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9d20: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
9d30: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
9d40: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
9d50: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
9d60: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
9d70: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
9d80: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
9d90: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
9da0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
9db0: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
9dc0: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
9dd0: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
9de0: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
9df0: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
9e00: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
9e10: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
9e20: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
9e30: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
9e40: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
9e50: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
9e60: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
9e70: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
9e80: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
9e90: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
9ea0: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
9eb0: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
9ec0: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
9ed0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
9ee0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
9ef0: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
9f00: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
9f10: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
9f20: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
9f30: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
9f40: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9f50: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
9f60: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
9f70: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
9f80: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
9f90: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
9fa0: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
9fb0: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
9fc0: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
9fd0: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
9fe0: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
9ff0: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
a000: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
a010: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a020: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
a030: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
a040: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
a050: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
a060: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
a070: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
a080: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
a090: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
a0a0: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
a0b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a0c0: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
a0d0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
a0e0: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
a0f0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
a100: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
a110: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
a120: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
a130: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a140: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
a150: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
a160: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a170: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
a180: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
a190: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
a1a0: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
a1b0: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
a1c0: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
a1d0: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
a1e0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
a1f0: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
a200: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
a210: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
a220: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
a230: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
a240: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
a250: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
a260: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
a270: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
a280: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
a290: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
a2a0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
a2b0: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
a2c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
a2d0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
a2e0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
a2f0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
a300: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
a310: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
a320: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
a330: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
a340: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
a350: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a360: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
a370: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
a380: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
a390: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
a3a0: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
a3b0: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
a3c0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
a3d0: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
a3e0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
a3f0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
a400: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
a410: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a420: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
a430: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
a440: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
a450: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
a460: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
a470: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
a480: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
a490: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
a4a0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a4b0: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
a4c0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
a4d0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
a4e0: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
a4f0: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
a500: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
a510: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
a520: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
a530: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
a540: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
a550: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
a560: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
a570: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
a580: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
a590: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
a5a0: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
a5b0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
a5c0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
a5d0: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
a5e0: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
a5f0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
a600: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
a610: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
a620: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
a630: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
a640: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
a650: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
a660: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
a670: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
a680: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
a690: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
a6a0: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
a6b0: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
a6c0: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
a6d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a6e0: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
a6f0: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
a700: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
a710: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
a720: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
a730: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
a740: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
a750: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
a760: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
a770: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
a780: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
a790: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
a7a0: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
a7b0: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
a7c0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
a7d0: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
a7e0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
a7f0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
a800: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
a810: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
a820: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
a830: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
a840: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
a850: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
a860: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
a870: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
a880: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
a890: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
a8a0: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
a8b0: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
a8c0: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
a8d0: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
a8e0: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
a8f0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
a900: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
a910: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
a920: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
a930: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
a940: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
a950: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
a960: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
a970: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
a980: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
a990: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
a9a0: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
a9b0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
a9c0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
a9d0: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
a9e0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
a9f0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
aa00: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
aa10: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
aa20: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
aa30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
aa40: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
aa50: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
aa60: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
aa70: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
aa80: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
aa90: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
aaa0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
aab0: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
aac0: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
aad0: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
aae0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
aaf0: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
ab00: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
ab10: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ab20: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
ab30: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
ab40: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
ab50: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
ab60: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
ab70: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
ab80: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
ab90: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
aba0: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
abb0: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
abc0: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
abd0: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
abe0: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
abf0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
ac00: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
ac10: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
ac20: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
ac30: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
ac40: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
ac50: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
ac60: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
ac70: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
ac80: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
ac90: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
aca0: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
acb0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
acc0: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
acd0: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
ace0: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
acf0: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
ad00: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ad10: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
ad20: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
ad30: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
ad40: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
ad50: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
ad60: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
ad70: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
ad80: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
ad90: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
ada0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
adb0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
adc0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
add0: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
ade0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
adf0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
ae00: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
ae10: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
ae20: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
ae30: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
ae40: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
ae50: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
ae60: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
ae70: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
ae80: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
ae90: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
aea0: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
aeb0: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
aec0: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
aed0: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
aee0: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
aef0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
af00: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
af10: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
af20: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
af30: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
af40: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
af50: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
af60: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
af70: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
af80: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
af90: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
afa0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
afb0: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
afc0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
afd0: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
afe0: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
aff0: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
b000: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
b010: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b020: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
b030: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
b040: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
b050: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
b060: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
b070: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
b080: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
b090: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
b0a0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b0b0: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
b0c0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
b0d0: 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
b0e0: 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
b0f0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
b100: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
b110: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
b120: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
b130: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
b140: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
b150: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
b160: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
b170: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
b180: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
b190: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
b1a0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
b1b0: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
b1c0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
b1d0: 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
b1e0: 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
b1f0: 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
b200: 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
b210: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
b220: 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
b230: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51  nding on the [SQ
b240: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
b250: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
b260: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
b270: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
b280: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
b290: 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
b2a0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
b2b0: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
b2c0: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
b2d0: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
b2e0: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
b2f0: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
b300: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
b310: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
b320: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
b330: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
b340: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
b350: 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
b360: 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
b370: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
b380: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
b390: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
b3a0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tions.**.** The 
b3b0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
b3c0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
b3d0: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f   used to make co
b3e0: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
b3f0: 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74  hanges to a [dat
b400: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
b410: 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  ].  The interfac
b420: 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a  e is similar to.
b430: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
b440: 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  ig()] except tha
b450: 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70  t the changes ap
b460: 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a  ply to a single.
b470: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
b480: 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66  nection] (specif
b490: 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
b4a0: 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65   argument).  The
b4b0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  .** sqlite3_db_c
b4c0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
b4d0: 65 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65  e should only be
b4e0: 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c   used immediatel
b4f0: 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64  y after.** the d
b500: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
b510: 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20 75 73  on is created us
b520: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ing [sqlite3_ope
b530: 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  n()],.** [sqlite
b540: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20  3_open16()], or 
b550: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
b560: 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ()].  .**.** The
b570: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
b580: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
b590: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
b5a0: 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67  is the.** config
b5b0: 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61  uration verb - a
b5c0: 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
b5d0: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
b5e0: 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20  at.** aspect of 
b5f0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
b600: 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
b610: 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a  ng configured..*
b620: 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63  * The only choic
b630: 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65  e for this value
b640: 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f   is [SQLITE_DBCO
b650: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e  NFIG_LOOKASIDE].
b660: 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72  .** New verbs ar
b670: 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61  e likely to be a
b680: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
b690: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
b6a0: 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  e..** Additional
b6b0: 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e   arguments depen
b6c0: 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a  d on the verb..*
b6d0: 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  *.** ^Calls to s
b6e0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
b6f0: 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
b700: 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  _OK if and only 
b710: 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69  if.** the call i
b720: 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63  s considered suc
b730: 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  cessful..*/.int 
b740: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
b750: 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
b760: 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
b770: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
b780: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
b790: 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  tines.**.** An i
b7a0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
b7b0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
b7c0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
b7d0: 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
b7e0: 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
b7f0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
b800: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
b810: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
b820: 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
b830: 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
b840: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
b850: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
b860: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
b870: 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
b880: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
b890: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b8a0: 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
b8b0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
b8c0: 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
b8d0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20  NFIG_MALLOC] or 
b8e0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
b8f0: 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20  ETMALLOC].  .** 
b900: 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
b910: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
b920: 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
b930: 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
b940: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
b950: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
b960: 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63  OC]).** during c
b970: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
b980: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
b990: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
b9a0: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
b9b0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
b9c0: 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74  system for SQLit
b9d0: 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
b9e0: 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d   of its.** dynam
b9f0: 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
ba00: 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
ba10: 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
ba20: 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c  th several [buil
ba30: 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
ba40: 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20  cators].** that 
ba50: 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64  are perfectly ad
ba60: 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
ba70: 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
ba80: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
ba90: 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
baa0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
bab0: 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
bac0: 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
bad0: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
bae0: 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
baf0: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
bb00: 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
bb10: 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
bb20: 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
bb30: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
bb40: 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
bb50: 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
bb60: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
bb70: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
bb80: 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
bb90: 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
bba0: 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
bbb0: 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
bbc0: 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
bbd0: 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
bbe0: 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
bbf0: 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
bc00: 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20  .** The xMalloc 
bc10: 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
bc20: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
bc30: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
bc40: 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
bc50: 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
bc60: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
bc70: 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c  y..** The xReall
bc80: 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 77  oc method must w
bc90: 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63  ork like realloc
bca0: 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  () from the stan
bcb0: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a 2a  dard C library.*
bcc0: 2a 20 77 69 74 68 20 74 68 65 20 65 78 63 65 70  * with the excep
bcd0: 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68 65  tion that if the
bce0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
bcf0: 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 20   to xRealloc is 
bd00: 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f  zero,.** xReallo
bd10: 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f  c must be a no-o
bd20: 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 20  p - it must not 
bd30: 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f  perform any allo
bd40: 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61  cation or.** dea
bd50: 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c  llocation.  ^SQL
bd60: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
bd70: 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61  hat the second a
bd80: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52  rgument to.** xR
bd90: 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73  ealloc is always
bda0: 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65   a value returne
bdb0: 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c  d by a prior cal
bdc0: 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a  l to xRoundup..*
bdd0: 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 65  * And so in case
bde0: 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75 70  s where xRoundup
bdf0: 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
be00: 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65  a positive numbe
be10: 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63  r,.** xRealloc c
be20: 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63 74  an perform exact
be30: 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e 64 61  ly as the standa
be40: 72 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c 6c  rd library reall
be50: 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c  oc() and.** stil
be60: 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e  l be in complian
be70: 63 65 20 77 69 74 68 20 74 68 69 73 20 73 70 65  ce with this spe
be80: 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  cification..**.*
be90: 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
bea0: 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
beb0: 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
bec0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
bed0: 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
bee0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
bef0: 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
bf00: 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
bf10: 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
bf20: 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
bf30: 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
bf40: 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
bf50: 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
bf60: 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
bf70: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
bf80: 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
bf90: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
bfa0: 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
bfb0: 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
bfc0: 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
bfd0: 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
bfe0: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
bff0: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
c000: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c010: 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
c020: 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
c030: 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
c040: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
c050: 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
c060: 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
c070: 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
c080: 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
c090: 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
c0a0: 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
c0b0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
c0c0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
c0d0: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
c0e0: 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
c0f0: 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
c100: 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
c110: 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
c120: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
c130: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c140: 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
c150: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
c160: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
c170: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
c180: 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .  (For example,
c190: 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
c1a0: 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
c1b0: 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
c1c0: 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
c1d0: 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
c1e0: 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
c1f0: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
c200: 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
c210: 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
c220: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
c230: 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
c240: 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
c250: 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
c260: 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
c270: 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
c280: 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
c290: 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
c2a0: 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
c2b0: 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
c2c0: 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
c2d0: 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
c2e0: 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
c2f0: 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
c300: 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
c310: 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
c320: 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
c330: 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
c340: 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
c350: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
c360: 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
c370: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c380: 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
c390: 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
c3a0: 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
c3b0: 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
c3c0: 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
c3d0: 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
c3e0: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
c3f0: 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
c400: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
c410: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
c420: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
c430: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
c440: 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
c450: 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
c460: 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
c470: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
c480: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
c490: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
c4a0: 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
c4b0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
c4c0: 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
c4d0: 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
c4e0: 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
c4f0: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
c500: 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
c510: 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
c520: 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
c530: 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
c540: 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
c550: 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
c560: 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
c570: 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
c580: 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
c590: 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
c5a0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
c5b0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
c5c0: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
c5d0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
c5e0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
c5f0: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
c600: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
c610: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
c620: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
c630: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
c640: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
c650: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
c660: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
c670: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
c680: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
c690: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
c6a0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
c6b0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
c6c0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
c6d0: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
c6e0: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
c6f0: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
c700: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
c710: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
c720: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
c730: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
c740: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
c750: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
c760: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
c770: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
c780: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
c790: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
c7a0: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
c7b0: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
c7c0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
c7d0: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
c7e0: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
c7f0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
c800: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
c810: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
c820: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
c830: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
c840: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
c850: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
c860: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
c870: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
c880: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
c890: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
c8a0: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
c8b0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
c8c0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
c8d0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
c8e0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
c8f0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
c900: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
c910: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
c920: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
c930: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
c940: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
c950: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
c960: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
c970: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
c980: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
c990: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
c9a0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
c9b0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
c9c0: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
c9d0: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
c9e0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
c9f0: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
ca00: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
ca10: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
ca20: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
ca30: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
ca40: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ca50: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
ca60: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
ca70: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
ca80: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
ca90: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
caa0: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
cab0: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
cac0: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
cad0: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
cae0: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
caf0: 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
cb00: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
cb10: 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
cb20: 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
cb30: 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
cb40: 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
cb50: 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
cb60: 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
cb70: 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
cb80: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
cb90: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
cba0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
cbb0: 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
cbc0: 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
cbd0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
cbe0: 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
cbf0: 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
cc00: 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
cc10: 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
cc20: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
cc30: 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
cc40: 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
cc50: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
cc60: 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
cc70: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
cc80: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
cc90: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
cca0: 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
ccb0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ccc0: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
ccd0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
cce0: 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
ccf0: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
cd00: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
cd10: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
cd20: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
cd30: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
cd40: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
cd50: 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
cd60: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
cd70: 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
cd80: 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
cd90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
cda0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
cdb0: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
cdc0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
cdd0: 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
cde0: 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
cdf0: 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
ce00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ce10: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
ce20: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
ce30: 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
ce40: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
ce50: 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
ce60: 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
ce70: 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
ce80: 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
ce90: 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
cea0: 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
ceb0: 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
cec0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
ced0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
cee0: 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
cef0: 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
cf00: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
cf10: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
cf20: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
cf30: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
cf40: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
cf50: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
cf60: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
cf70: 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
cf80: 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
cf90: 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
cfa0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
cfb0: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
cfc0: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
cfd0: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
cfe0: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
cff0: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
d000: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d010: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
d020: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d030: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
d040: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
d050: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
d060: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
d070: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
d080: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
d090: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
d0a0: 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
d0b0: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
d0c0: 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
d0d0: 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
d0e0: 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
d0f0: 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
d100: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
d110: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
d120: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
d130: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
d140: 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
d150: 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
d160: 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
d170: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
d180: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
d190: 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
d1a0: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
d1b0: 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
d1c0: 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
d1d0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d1e0: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
d1f0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
d200: 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
d210: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
d220: 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
d230: 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
d240: 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
d250: 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
d260: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
d270: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
d280: 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
d290: 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
d2a0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
d2b0: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
d2c0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
d2d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
d2e0: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
d2f0: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
d300: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
d310: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
d320: 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
d330: 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
d340: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
d350: 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
d360: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
d370: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
d380: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
d390: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
d3a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
d3b0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
d3c0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
d3d0: 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
d3e0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
d3f0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
d400: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
d410: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
d420: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
d430: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
d440: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
d450: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
d460: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
d470: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
d480: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
d490: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
d4a0: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
d4b0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
d4c0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
d4d0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
d4e0: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
d4f0: 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
d500: 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
d510: 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
d520: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
d530: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
d540: 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
d550: 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
d560: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
d570: 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
d580: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d590: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
d5a0: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
d5b0: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
d5c0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
d5d0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
d5e0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
d5f0: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
d600: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
d610: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
d620: 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  re.  The [sqlite
d630: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
d640: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
d650: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
d660: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
d670: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d680: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
d690: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
d6a0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
d6b0: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
d6c0: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
d6d0: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
d6e0: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
d6f0: 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
d700: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
d710: 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
d720: 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
d730: 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
d740: 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
d750: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
d760: 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a  MEMSTATUS</dt>.*
d770: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
d780: 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
d790: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
d7a0: 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
d7b0: 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
d7c0: 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
d7d0: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
d7e0: 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
d7f0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d800: 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
d810: 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
d820: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
d830: 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
d840: 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c  led, the .** fol
d850: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
d860: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
d870: 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
d880: 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
d890: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
d8a0: 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
d8b0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
d8c0: 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
d8d0: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
d8e0: 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
d8f0: 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c  _limit()].**   <
d900: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
d910: 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
d920: 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
d930: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
d940: 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
d950: 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
d960: 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
d970: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
d980: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
d990: 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
d9a0: 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
d9b0: 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
d9c0: 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
d9d0: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
d9e0: 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
d9f0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
da00: 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
da10: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
da20: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
da30: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
da40: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
da50: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
da60: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
da70: 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
da80: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
da90: 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
daa0: 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
dab0: 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
dac0: 77 68 69 63 68 20 74 68 65 20 73 63 72 61 63 68  which the scrach
dad0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
dae0: 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
daf0: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
db00: 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
db10: 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
db20: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
db30: 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
db40: 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20  locations (N).  
db50: 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
db60: 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
db70: 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 65  tiple of 16. The
db80: 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73 68   sz parameter sh
db90: 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62 79  ould be a few by
dba0: 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68  tes.** larger th
dbb0: 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73 63  an the actual sc
dbc0: 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71 75  ratch space requ
dbd0: 69 72 65 64 20 64 75 65 20 74 6f 20 69 6e 74 65  ired due to inte
dbe0: 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a  rnal overhead..*
dbf0: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
dc00: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
dc10: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
dc20: 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
dc30: 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
dc40: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
dc50: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
dc60: 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
dc70: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
dc80: 61 74 63 68 20 62 75 66 66 65 72 20 70 65 72 20  atch buffer per 
dc90: 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e  thread.  So.** N
dca0: 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
dcb0: 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  o the expected m
dcc0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
dcd0: 20 74 68 72 65 61 64 73 2e 20 20 5e 53 51 4c 69   threads.  ^SQLi
dce0: 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72  te will.** never
dcf0: 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74   require a scrat
dd00: 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69  ch buffer that i
dd10: 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 20 74 69  s more than 6 ti
dd20: 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
dd30: 0a 2a 2a 20 70 61 67 65 20 73 69 7a 65 2e 20 5e  .** page size. ^
dd40: 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20  If SQLite needs 
dd50: 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
dd60: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
dd70: 62 65 79 6f 6e 64 20 0a 2a 2a 20 77 68 61 74 20  beyond .** what 
dd80: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
dd90: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
dda0: 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
ddb0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
ddc0: 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
ddd0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
dde0: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
ddf0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
de00: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
de10: 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
de20: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
de30: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
de40: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
de50: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
de60: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
de70: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
de80: 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
de90: 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
dea0: 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20   implemenation. 
deb0: 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
dec0: 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
ded0: 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
dee0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
def0: 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
df00: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
df10: 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
df20: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
df30: 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e  IG_PCACHE option
df40: 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
df50: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
df60: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41  o this option: A
df70: 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79   pointer to 8-by
df80: 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65  te aligned.** me
df90: 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f  mory, the size o
dfa0: 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66  f each page buff
dfb0: 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
dfc0: 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
dfd0: 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
dfe0: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
dff0: 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
e000: 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
e010: 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
e020: 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
e030: 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36  een 512 and 3276
e040: 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65  8) plus a little
e050: 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a   extra for each.
e060: 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
e070: 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65   ^The page heade
e080: 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20  r size is 20 to 
e090: 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69  40 bytes dependi
e0a0: 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73  ng on.** the hos
e0b0: 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20  t architecture. 
e0c0: 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
e0d0: 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
e0e0: 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
e0f0: 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20  ** to make sz a 
e100: 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65  little too large
e110: 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
e120: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
e130: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
e140: 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
e150: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
e160: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
e170: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
e180: 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
e190: 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
e1a0: 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
e1b0: 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
e1c0: 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
e1d0: 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
e1e0: 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
e1f0: 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  e.  ^If addition
e200: 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
e210: 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
e220: 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
e230: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
e240: 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
e250: 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
e260: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
e270: 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
e280: 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
e290: 70 61 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6d  pace..** ^The im
e2a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
e2b0: 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f  ht use one or mo
e2c0: 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66  re of the N buff
e2d0: 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20  ers to hold .** 
e2e0: 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e  memory accountin
e2f0: 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54  g information. T
e300: 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68  he pointer in th
e310: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
e320: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67   must.** be alig
e330: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
e340: 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
e350: 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
e360: 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69   of SQLite.** wi
e370: 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
e380: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e390: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
e3a0: 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
e3b0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
e3c0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
e3d0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
e3e0: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
e3f0: 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
e400: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
e410: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
e420: 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
e430: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
e440: 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
e450: 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
e460: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
e470: 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
e480: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
e490: 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
e4a0: 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
e4b0: 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
e4c0: 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
e4d0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
e4e0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
e4f0: 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
e500: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
e510: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
e520: 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
e530: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
e540: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
e550: 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
e560: 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
e570: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
e580: 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
e590: 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
e5a0: 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
e5b0: 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
e5c0: 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
e5d0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
e5e0: 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
e5f0: 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
e600: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
e610: 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
e620: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
e630: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
e640: 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
e650: 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
e660: 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
e670: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
e680: 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
e690: 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
e6a0: 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
e6b0: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
e6c0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
e6d0: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
e6e0: 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
e6f0: 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
e700: 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
e710: 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
e720: 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
e730: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
e740: 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
e750: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e760: 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
e770: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
e780: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
e790: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
e7a0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
e7b0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
e7c0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
e7d0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
e7e0: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
e7f0: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
e800: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
e810: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
e820: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
e830: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
e840: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
e850: 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
e860: 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
e870: 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
e880: 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
e890: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
e8a0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
e8b0: 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
e8c0: 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
e8d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
e8e0: 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
e8f0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
e900: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
e910: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
e920: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
e930: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
e940: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
e950: 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
e960: 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
e970: 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
e980: 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
e990: 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
e9a0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
e9b0: 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
e9c0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
e9d0: 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
e9e0: 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
e9f0: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
ea00: 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
ea10: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
ea20: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
ea30: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
ea40: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
ea50: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
ea60: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
ea70: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
ea80: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
ea90: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
eaa0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
eab0: 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
eac0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
ead0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
eae0: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
eaf0: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
eb00: 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
eb10: 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
eb20: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
eb30: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
eb40: 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
eb50: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
eb60: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
eb70: 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
eb80: 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
eb90: 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
eba0: 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
ebb0: 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
ebc0: 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
ebd0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
ebe0: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
ebf0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
ec00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
ec10: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
ec20: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
ec30: 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
ec40: 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
ec50: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
ec60: 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
ec70: 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
ec80: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
ec90: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
eca0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
ecb0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ecc0: 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
ecd0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
ece0: 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
ecf0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
ed00: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
ed10: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
ed20: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
ed30: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
ed40: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
ed50: 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
ed60: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
ed70: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
ed80: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
ed90: 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
eda0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
edb0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
edc0: 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
edd0: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
ede0: 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
edf0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
ee00: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
ee10: 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
ee20: 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
ee30: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
ee40: 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
ee50: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
ee60: 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
ee70: 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
ee80: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
ee90: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
eea0: 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
eeb0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
eec0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
eed0: 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
eee0: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
eef0: 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
ef00: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
ef10: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
ef20: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
ef30: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
ef40: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
ef50: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
ef60: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
ef70: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
ef80: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
ef90: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
efa0: 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
efb0: 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
efc0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
efd0: 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
efe0: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
eff0: 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
f000: 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
f010: 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
f020: 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
f030: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
f040: 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
f050: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
f060: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
f070: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
f080: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
f090: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
f0a0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
f0b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
f0c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  * [sqlite3_pcach
f0d0: 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
f0e0: 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
f0f0: 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
f100: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
f110: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
f120: 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
f130: 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ^ </dd>.**.** <d
f140: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
f150: 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
f160: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
f170: 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
f180: 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
f190: 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
f1a0: 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
f1b0: 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
f1c0: 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
f1d0: 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
f1e0: 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
f1f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
f200: 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
f210: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
f220: 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
f230: 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
f240: 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
f250: 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
f260: 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
f270: 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
f280: 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
f290: 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
f2a0: 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
f2b0: 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
f2c0: 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
f2d0: 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
f2e0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
f2f0: 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
f300: 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
f310: 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
f320: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
f330: 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
f340: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
f350: 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
f360: 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
f370: 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
f380: 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
f390: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
f3a0: 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
f3b0: 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
f3c0: 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
f3d0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
f3e0: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
f3f0: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
f400: 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
f410: 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
f420: 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
f430: 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
f440: 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
f450: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
f460: 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
f470: 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
f480: 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
f490: 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
f4a0: 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
f4b0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
f4c0: 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
f4d0: 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
f4e0: 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
f4f0: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
f500: 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
f510: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
f520: 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
f530: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
f540: 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
f550: 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
f560: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f570: 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
f580: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
f590: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
f5a0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
f5b0: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
f5c0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
f5d0: 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
f5e0: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
f5f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
f600: 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
f610: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
f620: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
f630: 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
f640: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
f650: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
f660: 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
f670: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
f680: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
f690: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f6a0: 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
f6b0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
f6c0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
f6d0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
f6e0: 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
f6f0: 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
f700: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
f710: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f720: 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
f730: 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
f740: 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
f750: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f760: 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
f770: 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
f780: 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
f790: 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
f7a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
f7b0: 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
f7c0: 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
f7d0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
f7e0: 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
f7f0: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
f800: 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
f810: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f820: 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
f830: 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
f840: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
f850: 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
f860: 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
f870: 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
f880: 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
f890: 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
f8a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
f8b0: 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
f8c0: 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
f8d0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
f8e0: 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
f8f0: 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  4  /* sqlite3_pc
f900: 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
f910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f920: 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
f930: 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74      15  /* sqlit
f940: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
f950: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
f960: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
f970: 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
f980: 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
f990: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f9a0: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
f9b0: 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
f9c0: 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
f9d0: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
f9e0: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
f9f0: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
fa00: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
fa10: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
fa20: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
fa30: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
fa40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
fa50: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
fa60: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
fa70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fa80: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
fa90: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
faa0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
fab0: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
fac0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
fad0: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
fae0: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
faf0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
fb00: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
fb10: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
fb20: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
fb30: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
fb40: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
fb50: 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
fb60: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
fb70: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
fb80: 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
fb90: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
fba0: 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
fbb0: 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
fbc0: 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
fbd0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
fbe0: 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
fbf0: 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
fc00: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
fc10: 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
fc20: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
fc30: 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
fc40: 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
fc50: 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
fc60: 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
fc70: 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
fc80: 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
fc90: 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
fca0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
fcb0: 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
fcc0: 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
fcd0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
fce0: 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
fcf0: 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
fd00: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65  pointer to an me
fd10: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
fd20: 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
fd30: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
fd40: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
fd50: 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
fd60: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
fd70: 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
fd80: 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
fd90: 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
fda0: 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
fdb0: 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
fdc0: 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
fdd0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
fde0: 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
fdf0: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
fe00: 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
fe10: 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
fe20: 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
fe30: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
fe40: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
fe50: 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
fe60: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
fe70: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
fe80: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
fe90: 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
fea0: 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
feb0: 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
fec0: 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
fed0: 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
fee0: 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
fef0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
ff00: 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
ff10: 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
ff20: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
ff30: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
ff40: 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
ff50: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
ff60: 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
ff70: 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
ff80: 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
ff90: 6c 65 72 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20  ler.** multiple 
ffa0: 6f 66 20 38 2e 20 20 53 65 65 20 61 6c 73 6f 3a  of 8.  See also:
ffb0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
ffc0: 4c 4f 4f 4b 41 53 49 44 45 5d 3c 2f 64 64 3e 0a  LOOKASIDE]</dd>.
ffd0: 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
ffe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
fff0: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
10000 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
10010 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a  d* int int */...
10020 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10030 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
10040 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
10050 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  t Codes.**.** ^T
10060 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
10070 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
10080 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
10090 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
100a0 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
100b0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
100c0 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
100d0 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
100e0 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
100f0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
10100 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
10110 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
10120 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ity..*/.int sqli
10130 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
10140 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
10150 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
10160 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10170 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
10180 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  id.**.** ^Each e
10190 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74  ntry in an SQLit
101a0 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e  e table has a un
101b0 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
101c0 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
101d0 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
101e0 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
101f0 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
10200 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
10210 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
10220 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
10230 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
10240 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
10250 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
10260 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
10270 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
10280 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
10290 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
102a0 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
102b0 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
102c0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
102d0 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
102e0 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
102f0 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
10300 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  d..**.** ^This r
10310 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
10320 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
10330 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
10340 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
10350 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61  ERT] into the da
10360 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20  tabase from the 
10370 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10380 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
10390 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20  first argument. 
103a0 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
103b0 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20  ul [INSERT]s.** 
103c0 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
103d0 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
103e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
103f0 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
10400 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
10410 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
10420 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
10430 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69  , then the [rowi
10440 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
10450 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74  ed.** row is ret
10460 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
10470 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73  utine as long as
10480 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20   the trigger is 
10490 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
104a0 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
104b0 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65   terminates, the
104c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
104d0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  by this routine.
104e0 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68  ** reverts to th
104f0 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73  e last value ins
10500 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65  erted before the
10510 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 29   trigger fired.)
10520 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
10530 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
10540 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
10550 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
10560 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
10570 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
10580 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
10590 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
105a0 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
105b0 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
105c0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
105d0 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
105e0 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
105f0 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
10600 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
10610 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
10620 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
10630 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
10640 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
10650 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
10660 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
10670 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
10680 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
10690 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
106a0 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
106b0 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
106c0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
106d0 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
106e0 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
106f0 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
10700 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
10710 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
10720 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
10730 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
10740 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
10750 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
10760 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
10770 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
10780 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
10790 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
107a0 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
107b0 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
107c0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
107d0 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
107e0 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
107f0 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
10800 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
10810 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
10820 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
10830 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
10840 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
10850 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
10860 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
10870 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
10880 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
10890 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
108a0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
108b0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
108c0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
108d0 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
108e0 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
108f0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
10900 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
10910 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
10920 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
10930 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
10940 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
10950 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
10960 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
10970 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
10980 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
10990 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
109a0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
109b0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
109c0 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
109d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
109e0 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
109f0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
10a00 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
10a10 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
10a20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
10a30 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
10a40 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
10a50 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
10a60 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
10a70 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
10a80 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
10a90 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
10aa0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10ab0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
10ac0 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
10ad0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
10ae0 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
10af0 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
10b00 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
10b10 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
10b20 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
10b30 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
10b40 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
10b50 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
10b60 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
10b70 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
10b80 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
10b90 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
10ba0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
10bb0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
10bc0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
10bd0 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
10be0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
10bf0 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
10c00 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
10c10 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
10c20 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
10c30 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
10c40 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
10c50 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
10c60 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
10c70 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
10c80 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
10c90 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
10ca0 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
10cb0 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
10cc0 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
10cd0 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
10ce0 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
10cf0 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
10d00 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
10d10 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
10d20 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
10d30 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
10d40 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
10d50 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
10d60 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
10d70 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
10d80 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
10d90 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
10da0 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
10db0 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
10dc0 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
10dd0 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
10de0 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
10df0 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
10e00 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
10e10 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
10e20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
10e30 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
10e40 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
10e50 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
10e60 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
10e70 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
10e80 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
10e90 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
10ea0 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
10eb0 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
10ec0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
10ed0 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
10ee0 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
10ef0 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
10f00 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
10f10 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
10f20 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
10f30 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
10f40 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
10f50 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
10f60 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
10f70 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
10f80 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
10f90 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
10fa0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
10fb0 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
10fc0 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
10fd0 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
10fe0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
10ff0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
11000 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
11010 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
11020 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
11030 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
11040 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
11050 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
11060 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
11070 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
11080 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
11090 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
110a0 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
110b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
110c0 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
110d0 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
110e0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
110f0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
11100 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
11110 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
11120 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
11130 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
11140 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
11150 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
11160 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
11170 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
11180 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
11190 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
111a0 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
111b0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
111c0 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
111d0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
111e0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
111f0 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
11200 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
11210 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
11220 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
11230 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
11240 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
11250 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
11260 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
11270 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
11280 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
11290 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
112a0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
112b0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
112c0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
112d0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
112e0 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
112f0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
11300 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
11310 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
11320 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
11330 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
11340 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
11350 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
11360 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
11370 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
11380 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
11390 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
113a0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
113b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
113c0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
113d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
113e0 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
113f0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
11400 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
11410 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
11420 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
11430 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
11440 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a   by [INSERT],.**
11450 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
11460 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
11470 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
11480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11490 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
114a0 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75  ^(The count retu
114b0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
114c0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
114d0 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
114e0 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c  nges.** from all
114f0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
11500 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74   | trigger] cont
11510 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73  exts and changes
11520 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72   made by.** [for
11530 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
11540 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74  ]. However,.** t
11550 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  he count does no
11560 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
11570 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
11580 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f  ent [REPLACE] co
11590 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f  nstraints,.** do
115a0 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
115b0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
115c0 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20  or [DROP TABLE] 
115d0 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65  processing.  The
115e0 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  .** count does n
115f0 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20  ot include rows 
11600 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69  of views that fi
11610 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  re an [INSTEAD O
11620 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74  F trigger],.** t
11630 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53  hough if the INS
11640 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
11650 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66  makes changes of
11660 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20   its own, those 
11670 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20  changes .** are 
11680 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54  counted.)^.** ^T
11690 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  he sqlite3_total
116a0 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
116b0 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63  ion counts the c
116c0 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61  hanges as soon a
116d0 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  s.** the stateme
116e0 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
116f0 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20  em is completed 
11700 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
11710 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73  ent handle.** is
11720 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
11730 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
11740 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
11750 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  e()])..**.** See
11760 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
11770 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
11780 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
11790 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
117a0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
117b0 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
117c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
117d0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
117e0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
117f0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
11800 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
11810 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
11820 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
11830 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
11840 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
11850 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
11860 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
11870 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
11880 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
11890 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
118a0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
118b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
118c0 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
118d0 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
118e0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
118f0 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
11900 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
11910 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
11920 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
11930 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
11940 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
11950 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
11960 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
11970 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
11980 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
11990 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
119a0 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
119b0 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
119c0 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
119d0 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
119e0 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
119f0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
11a00 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
11a10 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
11a20 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
11a30 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
11a40 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
11a50 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
11a60 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
11a70 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
11a80 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
11a90 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
11aa0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
11ab0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11ac0 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
11ad0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
11ae0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
11af0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
11b00 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
11b10 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
11b20 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
11b30 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
11b40 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
11b50 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
11b60 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
11b70 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
11b80 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
11b90 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
11ba0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
11bb0 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
11bc0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
11bd0 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
11be0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
11bf0 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
11c00 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
11c10 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
11c20 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
11c30 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
11c40 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
11c50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
11c60 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
11c70 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
11c80 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
11c90 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
11ca0 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
11cb0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
11cc0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
11cd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
11ce0 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
11cf0 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
11d00 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
11d10 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
11d20 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
11d30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11d40 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
11d50 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
11d60 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
11d70 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
11d80 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
11d90 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
11da0 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
11db0 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
11dc0 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
11dd0 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
11de0 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
11df0 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
11e00 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
11e10 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
11e20 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
11e30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
11e40 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
11e50 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
11e60 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
11e70 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
11e80 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
11e90 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
11ea0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
11eb0 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
11ec0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
11ed0 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
11ee0 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
11ef0 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
11f00 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
11f10 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
11f20 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
11f30 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
11f40 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
11f50 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
11f60 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
11f70 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
11f80 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
11f90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
11fa0 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
11fb0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
11fc0 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
11fd0 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
11fe0 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
11ff0 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
12000 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
12010 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
12020 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
12030 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
12040 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
12050 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
12060 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
12070 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
12080 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
12090 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
120a0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
120b0 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
120c0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
120d0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
120e0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
120f0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
12100 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
12110 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
12120 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
12130 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
12140 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
12150 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
12160 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
12170 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
12180 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
12190 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
121a0 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
121b0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
121c0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
121d0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
121e0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
121f0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
12200 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
12210 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
12220 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
12230 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
12240 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
12250 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
12260 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
12270 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
12280 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
12290 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
122a0 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
122b0 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
122c0 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
122d0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
122e0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
122f0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
12300 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
12310 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
12320 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
12330 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
12340 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
12350 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
12360 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
12370 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
12380 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
12390 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
123a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
123b0 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
123c0 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
123d0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
123e0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
123f0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
12400 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
12410 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
12420 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
12430 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
12440 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
12450 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
12460 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
12470 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
12480 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
12490 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
124a0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
124b0 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
124c0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
124d0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
124e0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
124f0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
12500 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
12510 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
12520 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
12530 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
12540 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
12550 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
12560 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
12570 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
12580 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
12590 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
125a0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
125b0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
125c0 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
125d0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
125e0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
125f0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
12600 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
12610 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
12620 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
12630 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
12640 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
12650 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
12660 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12670 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
12680 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
12690 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
126a0 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
126b0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
126c0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
126d0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
126e0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
126f0 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
12700 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
12710 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
12720 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
12730 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
12740 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
12750 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
12760 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
12770 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
12780 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
12790 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
127a0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
127b0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
127c0 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
127d0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
127e0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
127f0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
12800 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
12810 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
12820 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
12830 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
12840 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
12850 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
12860 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
12870 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
12880 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
12890 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
128a0 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
128b0 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
128c0 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
128d0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
128e0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
128f0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
12900 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
12910 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
12920 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
12930 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
12940 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
12950 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
12960 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
12970 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
12980 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
12990 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
129a0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
129b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
129c0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
129d0 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
129e0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
129f0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
12a00 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
12a10 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
12a20 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
12a30 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
12a40 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
12a50 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
12a60 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
12a70 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
12a80 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
12a90 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
12aa0 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
12ab0 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
12ac0 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
12ad0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
12ae0 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
12af0 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
12b00 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
12b10 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
12b20 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
12b30 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
12b40 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
12b50 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
12b60 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
12b70 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
12b80 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
12b90 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
12ba0 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
12bb0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
12bc0 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
12bd0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
12be0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
12bf0 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
12c00 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
12c10 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
12c20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
12c30 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
12c40 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
12c50 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
12c60 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
12c70 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
12c80 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
12c90 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
12ca0 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
12cb0 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
12cc0 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
12cd0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
12ce0 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
12cf0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
12d00 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
12d10 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
12d20 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
12d30 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
12d40 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
12d50 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
12d60 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
12d70 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
12d80 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
12d90 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
12da0 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
12db0 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
12dc0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
12dd0 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
12de0 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
12df0 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
12e00 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
12e10 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
12e20 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
12e30 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
12e40 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
12e50 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
12e60 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
12e70 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
12e80 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
12e90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
12ea0 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
12eb0 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
12ec0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
12ed0 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
12ee0 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
12ef0 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
12f00 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
12f10 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
12f20 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
12f30 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
12f40 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
12f50 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
12f60 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
12f70 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
12f80 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
12f90 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
12fa0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
12fb0 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
12fc0 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
12fd0 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
12fe0 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
12ff0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
13000 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
13010 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
13020 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
13030 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
13040 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
13050 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
13060 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
13070 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
13080 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
13090 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
130a0 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
130b0 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
130c0 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
130d0 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
130e0 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
130f0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
13100 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
13110 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
13120 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
13130 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
13140 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
13150 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
13160 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
13170 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
13180 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
13190 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
131a0 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
131b0 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
131c0 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
131d0 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
131e0 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
131f0 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
13200 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
13210 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
13220 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
13230 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
13240 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
13250 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
13260 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
13270 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
13280 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
13290 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
132a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
132b0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
132c0 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
132d0 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
132e0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
132f0 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
13300 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
13310 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
13320 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
13330 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
13340 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
13350 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
13360 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
13370 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
13380 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
13390 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
133a0 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
133b0 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
133c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
133d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
133e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
133f0 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
13400 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
13410 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
13420 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
13430 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
13440 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
13450 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13460 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
13470 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  imeout.**.** ^Th
13480 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
13490 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
134a0 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
134b0 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
134c0 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
134d0 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
134e0 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
134f0 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
13500 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
13510 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
13520 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
13530 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
13540 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
13550 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
13560 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
13570 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
13580 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
13590 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
135a0 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
135b0 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
135c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
135d0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
135e0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
135f0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
13600 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  OCKED]..**.** ^C
13610 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
13620 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
13630 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
13640 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
13650 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
13660 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
13670 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
13680 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
13690 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
136a0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
136b0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
136c0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
136d0 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
136e0 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
136f0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
13700 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
13710 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
13720 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
13730 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
13740 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
13750 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
13760 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
13770 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ^.*/.int sqlite3
13780 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
13790 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
137a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
137b0 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
137c0 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
137d0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
137e0 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
137f0 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
13800 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
13810 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
13820 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
13830 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
13840 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
13850 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
13860 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
13870 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
13880 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
13890 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
138a0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
138b0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
138c0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
138d0 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
138e0 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
138f0 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
13900 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
13910 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
13920 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
13930 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
13940 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
13950 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
13960 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
13970 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
13980 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
13990 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
139a0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
139b0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
139c0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
139d0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
139e0 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
139f0 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
13a00 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
13a10 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
13a20 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
13a30 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
13a40 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
13a50 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
13a60 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
13a70 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
13a80 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
13a90 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
13aa0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
13ab0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
13ac0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
13ad0 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
13ae0 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
13af0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
13b00 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
13b10 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
13b20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
13b30 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
13b40 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
13b50 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
13b60 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
13b70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
13b80 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
13b90 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
13ba0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
13bb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
13bc0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
13bd0 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
13be0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
13bf0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
13c00 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
13c10 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  * As an example 
13c20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
13c30 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
13c40 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
13c50 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
13c60 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
13c70 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
13c80 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
13c90 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
13ca0 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
13cb0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
13cc0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
13cd0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
13ce0 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
13cf0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
13d00 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
13d10 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
13d20 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
13d30 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
13d40 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
13d50 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
13d60 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
13d70 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
13d80 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
13d90 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
13da0 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
13db0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
13dc0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
13dd0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
13de0 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
13df0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
13e00 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
13e10 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
13e20 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
13e30 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
13e40 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
13e50 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
13e60 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
13e70 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
13e80 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
13e90 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
13ea0 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
13eb0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
13ec0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
13ed0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
13ee0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
13ef0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
13f00 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
13f10 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
13f20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13f30 74 65 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te>.**.** ^The s
13f40 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
13f50 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
13f60 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
13f70 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
13f80 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
13f90 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
13fa0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
13fb0 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
13fc0 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
13fd0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
13fe0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
13ff0 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
14000 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
14010 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
14020 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
14030 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
14040 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
14050 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
14060 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
14070 2a 2a 20 69 74 20 73 68 6f 75 6c 64 20 70 61 73  ** it should pas
14080 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
14090 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
140a0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
140b0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
140c0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
140d0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
140e0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
140f0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
14100 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
14110 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
14120 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
14130 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
14140 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
14150 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
14160 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
14170 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
14180 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
14190 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
141a0 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
141b0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
141c0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
141d0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
141e0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
141f0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
14200 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
14210 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
14220 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
14230 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
14240 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
14250 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
14260 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
14270 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
14280 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
14290 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
142a0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
142b0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
142c0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
142d0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
142e0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
142f0 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
14300 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
14310 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
14320 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
14330 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
14340 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
14350 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
14360 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
14370 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
14380 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
14390 29 5d 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  )].)^.*/.int sql
143a0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
143b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
143c0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
143d0 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
143e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
143f0 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
14400 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
14410 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
14420 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
14430 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
14440 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
14450 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
14460 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
14470 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
14480 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
14490 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
144a0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
144b0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
144c0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
144d0 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
144e0 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
144f0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
14500 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
14510 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
14520 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
14530 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
14540 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
14550 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
14560 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
14570 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
14580 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
14590 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
145a0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
145b0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
145c0 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  library..**.** ^
145d0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
145e0 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
145f0 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
14600 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
14610 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
14620 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
14630 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
14640 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
14650 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
14660 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
14670 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
14680 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
14690 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
146a0 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
146b0 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
146c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
146d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
146e0 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
146f0 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
14700 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
14710 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
14720 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
14730 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  In sqlite3_snpri
14740 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
14750 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
14760 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
14770 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
14780 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
14790 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
147a0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
147b0 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
147c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
147d0 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
147e0 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
147f0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14800 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
14810 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
14820 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
14830 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
14840 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
14850 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
14860 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
14870 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
14880 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
14890 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
148a0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
148b0 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
148c0 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
148d0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
148e0 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
148f0 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
14900 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
14910 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
14920 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
14930 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
14940 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
14950 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
14960 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
14970 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
14980 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
14990 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
149a0 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
149b0 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
149c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
149d0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
149e0 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
149f0 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
14a00 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
14a10 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
14a20 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
14a30 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
14a40 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
14a50 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
14a60 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
14a70 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
14a80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
14a90 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
14aa0 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
14ab0 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
14ac0 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
14ad0 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
14ae0 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
14af0 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
14b00 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
14b10 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
14b20 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
14b30 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
14b40 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
14b50 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
14b60 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
14b70 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
14b80 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
14b90 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
14ba0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
14bb0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
14bc0 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
14bd0 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
14be0 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
14bf0 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
14c00 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
14c10 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
14c20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
14c30 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
14c40 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
14c50 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
14c60 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
14c70 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e  es a null-termin
14c80 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
14c90 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
14ca0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
14cb0 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
14cc0 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
14cd0 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
14ce0 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
14cf0 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
14d00 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
14d10 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
14d20 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
14d30 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
14d40 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
14d50 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
14d60 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
14d70 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
14d80 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
14d90 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
14da0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
14db0 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
14dc0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
14dd0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
14de0 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
14df0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
14e00 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
14e10 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
14e20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
14e30 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
14e40 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
14e50 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
14e60 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
14e70 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
14e80 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
14e90 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
14ea0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
14eb0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
14ec0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
14ed0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
14ee0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
14ef0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
14f00 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
14f10 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
14f20 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
14f30 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
14f40 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
14f50 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
14f60 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
14f70 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
14f80 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
14f90 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
14fa0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
14fb0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
14fc0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
14fd0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
14fe0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
14ff0 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
15000 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
15010 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
15020 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
15030 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
15040 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
15050 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
15060 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
15070 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
15080 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
15090 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
150a0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
150b0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
150c0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
150d0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
150e0 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
150f0 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
15100 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
15110 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
15120 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
15130 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
15140 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
15150 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
15160 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
15170 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
15180 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
15190 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
151a0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
151b0 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
151c0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
151d0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
151e0 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
151f0 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
15200 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
15210 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
15220 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
15230 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
15240 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
15250 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
15260 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
15270 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
15280 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
15290 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
152a0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
152b0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
152c0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
152d0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
152e0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
152f0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
15300 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
15310 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
15320 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
15330 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
15340 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
15350 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
15360 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
15370 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
15380 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
15390 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
153a0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
153b0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
153c0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
153d0 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
153e0 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
153f0 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
15400 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
15410 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
15420 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
15430 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
15440 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
15450 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
15460 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
15470 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
15480 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
15490 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
154a0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
154b0 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
154c0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
154d0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
154e0 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  har*, ...);../*.
154f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
15500 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
15510 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
15520 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
15530 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
15540 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
15550 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
15560 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
15570 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
15580 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
15590 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
155a0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
155b0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
155c0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
155d0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
155e0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
155f0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
15600 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
15610 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
15620 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
15630 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
15640 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
15650 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
15660 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
15670 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
15680 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
15690 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
156a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
156b0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
156c0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
156d0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
156e0 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
156f0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
15700 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
15710 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
15720 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
15730 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
15740 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
15750 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
15760 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
15770 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
15780 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
15790 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
157a0 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
157b0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
157c0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
157d0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
157e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
157f0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
15800 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
15810 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
15820 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
15830 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
15840 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
15850 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
15860 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
15870 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
15880 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
15890 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
158a0 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
158b0 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
158c0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
158d0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
158e0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
158f0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
15900 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
15910 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
15920 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
15930 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
15940 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
15950 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
15960 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
15970 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
15980 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
15990 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
159a0 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
159b0 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
159c0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
159d0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
159e0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
159f0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
15a00 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
15a10 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
15a20 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
15a30 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
15a40 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
15a50 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
15a60 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
15a70 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
15a80 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
15a90 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
15aa0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
15ab0 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
15ac0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
15ad0 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
15ae0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
15af0 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
15b00 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
15b10 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
15b20 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
15b30 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
15b40 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
15b50 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
15b60 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
15b70 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
15b80 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
15b90 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
15ba0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
15bb0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
15bc0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
15bd0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
15be0 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
15bf0 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
15c00 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
15c10 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
15c20 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
15c30 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
15c40 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
15c50 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
15c60 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
15c70 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15c80 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
15c90 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
15ca0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
15cb0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
15cc0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
15cd0 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
15ce0 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
15cf0 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
15d00 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
15d10 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
15d20 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
15d30 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
15d40 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
15d50 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
15d60 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
15d70 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
15d80 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
15d90 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
15da0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
15db0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
15dc0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
15dd0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
15de0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
15df0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
15e00 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
15e10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
15e20 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
15e30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15e40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
15e50 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
15e60 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
15e70 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
15e80 65 20 62 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a 2a  e boundary..**.*
15e90 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
15ea0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
15eb0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
15ec0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
15ed0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
15ee0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
15ef0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
15f00 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
15f10 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
15f20 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
15f30 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
15f40 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
15f50 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
15f60 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
15f70 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
15f80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
15f90 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
15fa0 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73  *.** The Windows
15fb0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
15fc0 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65  yer calls.** the
15fd0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
15fe0 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
15ff0 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
16000 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
16010 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
16020 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
16030 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
16040 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
16050 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
16060 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
16070 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
16080 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
16090 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
160a0 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64  ion errors are d
160b0 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
160c0 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65  they are reporte
160d0 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
160e0 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
160f0 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
16100 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
16110 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
16120 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
16130 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
16140 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
16150 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
16160 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
16170 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
16180 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
16190 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
161a0 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
161b0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
161c0 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
161d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
161e0 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
161f0 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
16200 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
16210 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
16220 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
16230 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
16240 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
16250 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
16260 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
16270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
16280 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
16290 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
162a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
162b0 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
162c0 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
162d0 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
162e0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
162f0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
16300 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
16310 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
16320 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
16330 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
16340 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
16350 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
16360 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
16370 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
16380 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
16390 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
163a0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
163b0 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
163c0 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
163d0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
163e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
163f0 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
16400 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16410 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
16420 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
16430 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
16440 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
16450 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
16460 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
16470 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
16480 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
16490 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
164a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
164b0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
164c0 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
164d0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
164e0 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
164f0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
16500 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
16510 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
16520 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
16530 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
16540 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
16550 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
16560 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
16570 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
16580 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
16590 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
165a0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
165b0 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
165c0 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
165d0 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
165e0 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
165f0 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
16600 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
16610 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
16620 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
16630 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
16640 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
16650 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
16660 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
16670 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
16680 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
16690 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
166a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
166b0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
166c0 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
166d0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
166e0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
166f0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
16700 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
16710 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
16720 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
16730 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
16740 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
16750 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
16760 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
16770 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
16780 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
16790 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
167a0 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
167b0 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
167c0 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
167d0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
167e0 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
167f0 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
16800 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
16810 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
16820 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
16830 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
16840 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
16850 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
16860 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
16870 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
16880 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
16890 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
168a0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
168b0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
168c0 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
168d0 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
168e0 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
168f0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
16900 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
16910 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
16920 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
16930 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
16940 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
16950 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
16960 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
16970 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
16980 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r P..**.** ^The 
16990 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
169a0 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
169b0 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
169c0 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
169d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
169e0 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
169f0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
16a00 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
16a10 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
16a20 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
16a30 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
16a40 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
16a50 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73  .** ^On all subs
16a60 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
16a70 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72  ns, the pseudo-r
16a80 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
16a90 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
16aa0 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
16ab0 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
16ac0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
16ad0 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
16ae0 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
16af0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
16b00 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
16b10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16b20 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
16b30 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
16b40 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
16b50 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
16b60 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a  sters a authoriz
16b70 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
16b80 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
16b90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16ba0 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
16bb0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
16bc0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
16bd0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16be0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
16bf0 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
16c00 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
16c10 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
16c20 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
16c30 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
16c40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
16c50 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
16c60 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
16c70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
16c80 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
16c90 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
16ca0 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
16cb0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
16cc0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
16cd0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
16ce0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
16cf0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
16d00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16d10 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
16d20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
16d30 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
16d40 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
16d50 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16d60 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
16d70 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
16d80 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
16d90 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
16da0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
16db0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
16dc0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
16dd0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
16de0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
16df0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
16e00 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
16e10 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
16e20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
16e30 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
16e40 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
16e50 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
16e60 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16e70 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
16e80 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
16e90 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
16ea0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
16eb0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
16ec0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
16ed0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
16ee0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
16ef0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
16f00 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
16f10 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
16f20 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
16f30 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
16f40 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
16f50 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
16f60 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
16f70 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
16f80 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
16f90 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
16fa0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16fb0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
16fc0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
16fd0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
16fe0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
16ff0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
17000 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
17010 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
17020 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
17030 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
17040 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
17050 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
17060 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
17070 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
17080 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
17090 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
170a0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
170b0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
170c0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
170d0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
170e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
170f0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
17100 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
17110 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
17120 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
17130 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
17140 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
17150 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
17160 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
17170 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
17180 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
17190 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
171a0 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
171b0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
171c0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
171d0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
171e0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
171f0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
17200 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
17210 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
17220 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
17230 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
17240 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
17250 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
17260 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
17270 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
17280 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
17290 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
172a0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
172b0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
172c0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
172d0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
172e0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
172f0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
17300 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
17310 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
17320 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
17330 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
17340 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
17350 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
17360 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
17370 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
17380 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
17390 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
173a0 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
173b0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
173c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
173d0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
173e0 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
173f0 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
17400 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
17410 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
17420 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
17430 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
17440 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
17450 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
17460 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
17470 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17480 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
17490 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
174a0 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
174b0 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
174c0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
174d0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
174e0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
174f0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
17500 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
17510 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
17520 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
17530 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
17540 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
17550 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
17560 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
17570 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
17580 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
17590 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
175a0 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
175b0 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
175c0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
175d0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
175e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
175f0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
17600 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
17610 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
17620 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
17630 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
17640 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
17650 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
17660 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
17670 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
17680 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
17690 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
176a0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
176b0 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
176c0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
176d0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
176e0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
176f0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
17700 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
17710 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
17720 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
17730 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
17740 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
17750 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
17760 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
17770 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
17780 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
17790 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
177a0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
177b0 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
177c0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
177d0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
177e0 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
177f0 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
17800 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
17810 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
17820 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
17830 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
17840 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
17850 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
17860 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
17870 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
17880 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
17890 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
178a0 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
178b0 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
178c0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
178d0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
178e0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
178f0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
17900 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
17910 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
17920 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
17930 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
17940 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
17950 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17960 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
17970 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
17980 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
17990 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
179a0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
179b0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
179c0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
179d0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
179e0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
179f0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
17a00 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
17a10 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
17a20 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
17a30 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
17a40 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
17a50 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
17a60 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
17a70 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
17a80 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
17a90 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
17aa0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
17ab0 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
17ac0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
17ad0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17ae0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
17af0 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
17b00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
17b10 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
17b20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
17b30 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
17b40 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
17b50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
17b60 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
17b70 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
17b80 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
17b90 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
17ba0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
17bb0 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
17bc0 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
17bd0 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
17be0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
17bf0 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
17c00 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
17c10 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
17c20 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
17c30 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
17c40 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
17c50 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  a change..*/.int
17c60 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
17c70 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
17c80 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
17c90 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
17ca0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
17cb0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
17cc0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
17cd0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
17ce0 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
17cf0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
17d00 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
17d10 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
17d20 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
17d30 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
17d40 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
17d50 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
17d60 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
17d70 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
17d80 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
17d90 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
17da0 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
17db0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
17dc0 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
17dd0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
17de0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
17df0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
17e00 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
17e10 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
17e20 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
17e30 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  on..*/.#define S
17e40 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
17e50 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
17e60 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
17e70 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
17e80 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
17e90 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
17ea0 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
17eb0 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
17ec0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
17ed0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
17ee0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
17ef0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
17f00 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
17f10 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
17f20 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
17f30 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
17f40 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
17f50 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
17f60 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
17f70 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
17f80 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
17f90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17fa0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
17fb0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
17fc0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
17fd0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
17fe0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
17ff0 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
18000 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
18010 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
18020 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18030 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
18040 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
18050 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
18060 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
18070 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
18080 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
18090 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
180a0 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
180b0 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
180c0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
180d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
180e0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
180f0 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
18100 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
18110 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
18120 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
18130 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
18140 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
18150 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
18160 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18170 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
18180 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
18190 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
181a0 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
181b0 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
181c0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
181d0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
181e0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
181f0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
18200 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
18210 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
18220 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
18230 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
18240 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
18250 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
18260 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
18270 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
18280 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
18290 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
182a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
182b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
182c0 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
182d0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
182e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
182f0 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
18300 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
18310 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
18320 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18330 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18340 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
18350 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
18360 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
18370 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18380 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18390 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
183a0 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
183b0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
183c0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
183d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
183e0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
183f0 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
18400 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
18410 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18430 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
18440 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
18450 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
18460 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
18470 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
18480 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
18490 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
184a0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
184b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
184c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
184d0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
184e0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
184f0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
18500 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
18510 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18520 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
18530 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
18540 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
18550 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18560 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
18570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
18580 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18590 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
185a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
185b0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
185c0 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
185d0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
185e0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
185f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18600 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
18610 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
18620 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18630 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18640 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18650 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
18660 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
18670 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
18680 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
18690 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
186a0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
186b0 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
186c0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
186d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
186e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
186f0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
18700 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
18710 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
18720 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18730 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18740 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
18750 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
18760 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
18770 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18780 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18790 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
187a0 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
187b0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
187c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
187d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
187e0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
187f0 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
18800 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
18810 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18820 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18830 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
18840 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
18850 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
18860 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18870 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
18880 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
18890 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
188a0 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
188b0 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
188c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
188d0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
188e0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
188f0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
18900 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
18910 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
18920 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
18930 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
18940 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
18950 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18960 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
18970 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
18980 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
18990 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
189a0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
189b0 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
189c0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
189d0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
189e0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
189f0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
18a00 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
18a10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
18a20 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
18a30 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
18a40 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18a50 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
18a60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
18a70 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
18a80 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
18a90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18aa0 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
18ab0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
18ac0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
18ad0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
18ae0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18af0 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
18b00 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
18b10 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
18b20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18b30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18b40 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
18b50 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
18b60 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
18b70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18b80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18b90 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
18ba0 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
18bb0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
18bc0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
18bd0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18be0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
18bf0 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
18c00 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18c10 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
18c20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18c30 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
18c40 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
18c50 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18c60 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
18c70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18c80 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
18c90 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
18ca0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
18cb0 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
18cc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18cd0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
18ce0 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
18cf0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
18d00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18d10 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
18d20 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
18d30 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
18d40 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
18d50 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
18d60 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
18d70 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
18d80 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
18d90 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
18da0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
18db0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
18dc0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
18dd0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
18de0 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
18df0 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
18e00 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
18e10 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
18e20 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
18e30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
18e40 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
18e50 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
18e60 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
18e70 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
18e80 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
18e90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
18ea0 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
18eb0 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
18ec0 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
18ed0 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
18ee0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
18ef0 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
18f00 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
18f10 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
18f20 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
18f30 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
18f40 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
18f50 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
18f60 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
18f70 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
18f80 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  gger.)^.**.** ^T
18f90 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
18fa0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
18fb0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
18fc0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
18fd0 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
18fe0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
18ff0 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
19000 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
19010 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
19020 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
19030 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
19040 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
19050 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
19060 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
19070 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a  nt took to run..
19080 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
19090 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
190a0 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
190b0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
190c0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
190d0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
190e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
190f0 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
19100 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
19110 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
19120 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
19130 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
19140 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
19150 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
19160 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
19170 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69  is routine confi
19180 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b  gures a callback
19190 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a   function - the.
191a0 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  ** progress call
191b0 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69  back - that is i
191c0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
191d0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a  lly during long.
191e0 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ** running calls
191f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
19200 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
19210 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  tep()] and.** [s
19220 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
19230 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ()].  An example
19240 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
19250 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
19260 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
19270 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
19280 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
19290 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
192a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
192b0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
192c0 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
192d0 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
192e0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
192f0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
19300 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
19310 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
19320 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
19330 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
19340 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
19350 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  r must not do an
19360 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
19370 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
19380 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19390 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
193a0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
193b0 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
193c0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
193d0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
193e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
193f0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
19400 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
19410 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
19420 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
19430 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
19440 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
19450 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
19460 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
19470 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
19480 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
19490 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
194a0 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
194b0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
194c0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
194d0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
194e0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
194f0 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61  se file whose na
19500 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74  me is given by t
19510 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  he.** filename a
19520 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
19530 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
19540 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
19550 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
19560 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
19570 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
19580 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
19590 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
195a0 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
195b0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
195c0 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
195d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
195e0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
195f0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
19600 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
19610 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
19620 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
19630 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
19640 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
19650 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
19660 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
19670 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
19680 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
19690 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
196a0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
196b0 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
196c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
196d0 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
196e0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
196f0 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
19700 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
19710 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
19720 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
19730 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
19740 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
19750 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
19760 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
19770 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
19780 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
19790 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
197a0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
197b0 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
197c0 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
197d0 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
197e0 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
197f0 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
19800 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
19810 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
19820 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
19830 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
19840 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
19850 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
19860 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
19870 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
19880 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
19890 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
198a0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
198b0 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65   order if sqlite
198c0 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73  3_open16() is us
198d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
198e0 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
198f0 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
19900 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
19910 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
19920 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
19930 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19940 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
19950 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
19960 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
19970 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
19980 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
19990 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
199a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
199b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
199c0 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
199d0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
199e0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
199f0 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
19a00 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
19a10 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
19a20 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
19a30 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
19a40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19a50 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
19a60 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
19a70 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19a80 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
19a90 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
19aa0 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
19ab0 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
19ac0 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
19ad0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
19ae0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
19af0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
19b00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
19b10 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61  AREDCACHE],.** a
19b20 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
19b30 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
19b40 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
19b50 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
19b60 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
19b70 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
19b80 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
19b90 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
19ba0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
19bb0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
19bc0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
19bd0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
19be0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
19bf0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
19c00 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
19c10 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
19c20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
19c30 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
19c40 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
19c50 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
19c60 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
19c70 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
19c80 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
19c90 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
19ca0 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
19cb0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
19cc0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
19cd0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
19ce0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
19cf0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
19d00 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
19d10 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
19d20 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
19d30 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
19d40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
19d50 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
19d60 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
19d70 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
19d80 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69   is creates it i
19d90 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
19da0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
19db0 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
19dc0 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
19dd0 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
19de0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
19df0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
19e00 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
19e10 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
19e20 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
19e30 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
19e40 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
19e50 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
19e60 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
19e70 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  ve or one of the
19e80 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
19e90 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e  own above combin
19ea0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
19eb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
19ec0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
19ed0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a  EN_FULLMUTEX],.*
19ee0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  * [SQLITE_OPEN_S
19ef0 48 41 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f  HAREDCACHE] and/
19f00 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
19f10 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
19f20 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  gs,.** then the 
19f30 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
19f40 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
19f50 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
19f60 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
19f70 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
19f80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19f90 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
19fa0 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
19fb0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
19fc0 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
19fd0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
19fe0 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
19ff0 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
1a000 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1a010 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
1a020 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1a030 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
1a040 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
1a050 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a060 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
1a070 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
1a080 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1a090 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
1a0a0 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
1a0b0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
1a0c0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1a0d0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
1a0e0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
1a0f0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1a100 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1a110 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a120 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
1a130 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
1a140 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1a150 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
1a160 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1a170 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
1a180 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
1a190 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
1a1a0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1a1b0 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
1a1c0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1a1d0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
1a1e0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
1a1f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
1a200 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
1a210 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
1a220 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
1a230 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
1a240 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
1a250 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
1a260 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
1a270 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
1a280 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1a290 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
1a2a0 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1a2b0 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
1a2c0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
1a2d0 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
1a2e0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1a2f0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1a300 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
1a310 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
1a320 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
1a330 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
1a340 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
1a350 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
1a360 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
1a370 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
1a380 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
1a390 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
1a3a0 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
1a3b0 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
1a3c0 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
1a3d0 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
1a3e0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
1a3f0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
1a400 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
1a410 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
1a420 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
1a430 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1a440 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1a450 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1a460 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
1a470 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
1a480 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
1a490 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
1a4a0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1a4b0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1a4c0 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
1a4d0 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
1a4e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1a4f0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  closed..**.** ^T
1a500 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1a510 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1a520 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
1a530 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
1a540 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1a550 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
1a560 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1a570 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
1a580 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
1a590 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a5a0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
1a5b0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
1a5c0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1a5d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1a5e0 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
1a5f0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1a600 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
1a610 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
1a620 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
1a630 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
1a640 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
1a650 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
1a660 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
1a670 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1a680 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
1a690 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
1a6a0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
1a6b0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
1a6c0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
1a6d0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
1a6e0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
1a6f0 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
1a700 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
1a710 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
1a720 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
1a730 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1a740 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1a750 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73  n_v2()..*/.int s
1a760 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
1a770 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
1a780 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1a790 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1a7a0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
1a7b0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
1a7c0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1a7d0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
1a7e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1a7f0 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
1a800 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1a810 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1a820 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
1a830 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
1a840 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1a850 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1a860 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
1a870 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
1a880 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
1a890 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1a8a0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1a8b0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
1a8c0 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
1a8d0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1a8e0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
1a8f0 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
1a900 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
1a910 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1a920 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
1a930 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
1a940 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
1a950 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a960 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
1a970 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20   Messages.**.** 
1a980 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
1a990 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
1a9a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1a9b0 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
1a9c0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
1a9d0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1a9e0 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
1a9f0 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
1aa00 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a  e3_* API call.**
1aa10 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1aa20 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1aa30 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70  nection]. If a p
1aa40 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
1aa50 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20  iled.** but the 
1aa60 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
1aa70 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
1aa80 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1aa90 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
1aaa0 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
1aab0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73  defined.  ^The s
1aac0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1aad0 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
1aae0 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
1aaf0 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
1ab00 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
1ab10 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
1ab20 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1ab30 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
1ab40 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
1ab50 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
1ab60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ab70 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
1ab80 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
1ab90 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
1aba0 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
1abb0 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
1abc0 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
1abd0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1abe0 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
1abf0 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
1ac00 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
1ac10 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
1ac20 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
1ac30 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
1ac40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
1ac50 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
1ac60 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
1ac70 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
1ac80 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
1ac90 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
1aca0 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
1acb0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
1acc0 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
1acd0 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
1ace0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
1acf0 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
1ad00 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
1ad10 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
1ad20 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
1ad30 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
1ad40 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
1ad50 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
1ad60 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
1ad70 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
1ad80 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
1ad90 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
1ada0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
1adb0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
1adc0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
1add0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
1ade0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
1adf0 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
1ae00 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
1ae10 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
1ae20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
1ae30 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
1ae40 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
1ae50 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
1ae60 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
1ae70 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
1ae80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ae90 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
1aea0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
1aeb0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
1aec0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
1aed0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
1aee0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
1aef0 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
1af00 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
1af10 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
1af20 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
1af30 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
1af40 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
1af50 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
1af60 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
1af70 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
1af80 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
1af90 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
1afa0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
1afb0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
1afc0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
1afd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1afe0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
1aff0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
1b000 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
1b010 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
1b020 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
1b030 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
1b040 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
1b050 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
1b060 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1b070 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
1b080 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
1b090 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
1b0a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
1b0b0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
1b0c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b0d0 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e  EF: SQL Statemen
1b0e0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
1b0f0 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
1b100 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
1b110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
1b120 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
1b130 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
1b140 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
1b150 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
1b160 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ent..** This obj
1b170 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79  ect is variously
1b180 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65   known as a "pre
1b190 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22  pared statement"
1b1a0 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c   or a.** "compil
1b1b0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1b1c0 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61  " or simply as a
1b1d0 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a   "statement"..**
1b1e0 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20  .** The life of 
1b1f0 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  a statement obje
1b200 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e  ct goes somethin
1b210 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  g like this:.**.
1b220 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
1b230 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63  Create the objec
1b240 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1b250 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1b260 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20  r a related.**  
1b270 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a      function..**
1b280 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
1b290 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d  s to [host param
1b2a0 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65  eters] using the
1b2b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1b2c0 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66  ).**      interf
1b2d0 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  aces..** <li> Ru
1b2e0 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
1b2f0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
1b300 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
1b310 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
1b320 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65   Reset the state
1b330 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
1b340 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
1b350 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
1b360 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
1b370 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
1b380 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1b390 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
1b3a0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1b3b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
1b3c0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
1b3d0 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e  Refer to documen
1b3e0 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  tation on indivi
1b3f0 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f  dual methods abo
1b400 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ve for additiona
1b410 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
1b420 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1b430 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
1b440 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
1b450 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b460 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
1b470 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
1b480 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
1b490 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
1b4a0 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
1b4b0 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
1b4c0 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
1b4d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
1b4e0 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
1b4f0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1b500 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1b510 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
1b520 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
1b530 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
1b540 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1b550 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
1b560 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
1b570 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
1b580 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
1b590 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
1b5a0 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
1b5b0 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
1b5c0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
1b5d0 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
1b5e0 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68  t construct.  Th
1b5f0 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
1b600 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74  ns the old limit
1b610 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
1b620 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
1b630 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
1b640 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
1b650 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46  nchanged..** ^(F
1b660 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74  or the limit cat
1b670 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f  egory of SQLITE_
1b680 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20  LIMIT_XYZ there 
1b690 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
1b6a0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
1b6b0 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61  und].** set by a
1b6c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20   compile-time C 
1b6d0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1b6e0 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69  ro named .** [li
1b6f0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
1b700 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20  X_XYZ]..** (The 
1b710 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
1b720 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
1b730 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a   to "_MAX_".))^.
1b740 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20  ** ^Attempts to 
1b750 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
1b760 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
1b770 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
1b780 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
1b790 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
1b7a0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a  d upper bound..*
1b7b0 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
1b7c0 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
1b7d0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
1b7e0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
1b7f0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
1b800 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
1b810 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
1b820 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
1b830 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
1b840 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
1b850 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1b860 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
1b870 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
1b880 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
1b890 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
1b8a0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
1b8b0 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
1b8c0 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
1b8d0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
1b8e0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
1b8f0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
1b900 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
1b910 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
1b920 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
1b930 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
1b940 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
1b950 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
1b960 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
1b970 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
1b980 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
1b990 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
1b9a0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
1b9b0 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
1b9c0 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
1b9d0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
1b9e0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
1b9f0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
1ba00 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
1ba10 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1ba20 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
1ba30 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
1ba40 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
1ba50 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
1ba60 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
1ba70 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
1ba80 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
1ba90 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
1baa0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
1bab0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1bac0 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
1bad0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
1bae0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
1baf0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
1bb00 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
1bb10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
1bb20 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
1bb30 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
1bb40 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1bb50 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
1bb60 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
1bb70 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
1bb80 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
1bb90 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
1bba0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
1bbb0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
1bbc0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
1bbd0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
1bbe0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
1bbf0 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
1bc00 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1bc10 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
1bc20 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
1bc30 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
1bc40 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
1bc50 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
1bc60 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
1bc70 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
1bc80 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
1bc90 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
1bca0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
1bcb0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1bcc0 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
1bcd0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1bce0 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
1bcf0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
1bd00 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 29 5e  table row.<dd>)^
1bd10 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1bd20 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1bd30 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1bd40 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
1bd50 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
1bd60 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
1bd70 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
1bd80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1bd90 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
1bda0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1bdb0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1bdc0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
1bdd0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
1bde0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
1bdf0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
1be00 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
1be10 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1be20 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
1be30 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
1be40 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
1be50 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
1be60 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1be70 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
1be80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1be90 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
1bea0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
1beb0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
1bec0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
1bed0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1bee0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1bef0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
1bf00 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1bf10 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
1bf20 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
1bf30 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
1bf40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1bf50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1bf60 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
1bf70 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1bf80 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
1bf90 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
1bfa0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
1bfb0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
1bfc0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
1bfd0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
1bfe0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1bff0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
1c000 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
1c010 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1c020 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
1c030 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
1c040 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1c050 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
1c060 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
1c070 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1c080 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
1c090 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
1c0a0 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
1c0b0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1c0c0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
1c0d0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
1c0e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c0f0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
1c100 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
1c110 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
1c120 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
1c130 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
1c140 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1c150 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1c160 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
1c170 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c180 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69  m number of vari
1c190 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20  ables in an SQL 
1c1a0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63  statement that c
1c1b0 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c  an.** be bound.<
1c1c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1c1d0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c1e0 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
1c1f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c200 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
1c210 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
1c220 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
1c230 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
1c240 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
1c250 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1c260 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
1c270 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c280 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
1c290 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
1c2a0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c2b0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
1c2c0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
1c2d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c2e0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
1c2f0 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
1c300 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c310 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
1c320 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
1c330 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c340 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
1c350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
1c360 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c370 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
1c380 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
1c390 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c3a0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
1c3b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c3c0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
1c3d0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1c3e0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
1c3f0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
1c400 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1c410 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
1c420 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
1c430 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
1c440 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1c450 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    10../*.** CAPI
1c460 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
1c470 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
1c480 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
1c490 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
1c4a0 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
1c4b0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
1c4c0 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
1c4d0 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
1c4e0 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
1c4f0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
1c500 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
1c510 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
1c520 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1c530 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
1c540 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c550 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
1c560 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
1c570 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
1c580 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1c590 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
1c5a0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
1c5b0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
1c5c0 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
1c5d0 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
1c5e0 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
1c5f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
1c600 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
1c610 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
1c620 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
1c630 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
1c640 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
1c650 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
1c660 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
1c670 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
1c680 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
1c690 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
1c6a0 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
1c6b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
1c6c0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1c6d0 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
1c6e0 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
1c6f0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
1c700 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
1c710 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
1c720 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
1c730 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
1c740 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
1c750 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
1c760 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
1c770 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
1c780 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
1c790 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
1c7a0 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74  Sql.  ^When nByt
1c7b0 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
1c7c0 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
1c7d0 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
1c7e0 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
1c7f0 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
1c800 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
1c810 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
1c820 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
1c830 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
1c840 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
1c850 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
1c860 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
1c870 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
1c880 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
1c890 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
1c8a0 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
1c8b0 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
1c8c0 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
1c8d0 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
1c8e0 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
1c8f0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1c900 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
1c910 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
1c920 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
1c930 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
1c940 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  s..**.** ^If pzT
1c950 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
1c960 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
1c970 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
1c980 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
1c990 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
1c9a0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
1c9b0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1c9c0 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
1c9d0 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
1c9e0 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
1c9f0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
1ca00 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
1ca10 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
1ca20 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
1ca30 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
1ca40 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
1ca50 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
1ca60 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
1ca70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1ca80 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
1ca90 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
1caa0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
1cab0 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
1cac0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
1cad0 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
1cae0 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
1caf0 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
1cb00 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
1cb10 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
1cb20 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
1cb30 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
1cb40 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
1cb50 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
1cb60 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
1cb70 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1cb80 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
1cb90 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
1cba0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1cbb0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1cbc0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
1cbd0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
1cbe0 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
1cbf0 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
1cc00 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
1cc10 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
1cc20 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
1cc30 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1cc40 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
1cc50 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
1cc60 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
1cc70 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
1cc80 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1cc90 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
1cca0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1ccb0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
1ccc0 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
1ccd0 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
1cce0 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
1ccf0 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
1cd00 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
1cd10 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1cd20 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
1cd30 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
1cd40 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
1cd50 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
1cd60 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
1cd70 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
1cd80 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
1cd90 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
1cda0 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
1cdb0 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
1cdc0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
1cdd0 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
1cde0 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
1cdf0 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
1ce00 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
1ce10 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
1ce20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
1ce30 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
1ce40 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
1ce50 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
1ce60 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
1ce70 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
1ce80 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
1ce90 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
1cea0 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
1ceb0 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
1cec0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
1ced0 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
1cee0 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
1cef0 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
1cf00 20 5e 49 66 20 74 68 65 20 73 63 68 65 6d 61 20   ^If the schema 
1cf10 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a  has changed in.*
1cf20 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b  * a way that mak
1cf30 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  es the statement
1cf40 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64   no longer valid
1cf50 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1cf60 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a  )] will still.**
1cf70 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1cf80 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e  SCHEMA].  But un
1cf90 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20  like the legacy 
1cfa0 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54  behavior, [SQLIT
1cfb0 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20  E_SCHEMA] is.** 
1cfc0 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f  now a fatal erro
1cfd0 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  r.  Calling [sql
1cfe0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1cff0 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f  )] again will no
1d000 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72  t make the.** er
1d010 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f  ror go away.  No
1d020 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33  te: use [sqlite3
1d030 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69  _errmsg()] to fi
1d040 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f  nd the text.** o
1d050 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72  f the parsing er
1d060 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73  ror that results
1d070 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53   in an [SQLITE_S
1d080 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a  CHEMA] return..*
1d090 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1d0a0 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
1d0b0 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
1d0c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1d0d0 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
1d0e0 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
1d0f0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
1d100 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
1d110 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
1d120 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
1d130 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
1d140 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
1d150 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
1d160 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
1d170 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
1d180 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
1d190 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
1d1a0 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
1d1b0 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
1d1c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1d1d0 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
1d1e0 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
1d1f0 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
1d200 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
1d210 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
1d220 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
1d230 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
1d240 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
1d250 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
1d260 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
1d270 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1d280 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
1d290 20 6f 66 20 61 20 5b 70 61 72 61 6d 65 74 65 72   of a [parameter
1d2a0 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
1d2b0 72 5d 20 69 6e 20 74 68 65 20 57 48 45 52 45 20  r] in the WHERE 
1d2c0 63 6c 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a 20  clause might.** 
1d2d0 63 68 61 6e 67 65 20 74 68 65 20 71 75 65 72 79  change the query
1d2e0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
1d2f0 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  ement, then the 
1d300 73 74 61 74 65 6d 65 6e 74 20 6d 61 79 20 62 65  statement may be
1d310 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1d320 79 20 72 65 63 6f 6d 70 69 6c 65 64 20 28 61 73  y recompiled (as
1d330 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
1d340 65 6e 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  en a schema chan
1d350 67 65 29 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge) on the first
1d360 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
1d370 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
1d380 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 20  wing any change 
1d390 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  to the .** [sqli
1d3a0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
1d3b0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 65  bindings] of the
1d3c0 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
1d3d0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
1d3e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1d3f0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
1d400 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1d410 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1d420 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1d430 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1d440 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1d450 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
1d460 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1d470 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1d480 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1d490 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1d4a0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1d4b0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1d4c0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1d4d0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1d4e0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
1d4f0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1d500 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1d510 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1d520 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1d530 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
1d540 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1d550 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1d560 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1d570 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1d580 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1d590 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
1d5a0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1d5b0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1d5c0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1d5d0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1d5e0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1d5f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1d600 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1d610 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1d620 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1d630 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1d640 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1d650 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1d660 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1d670 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1d680 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
1d690 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1d6a0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1d6b0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1d6c0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1d6d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1d6e0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
1d6f0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1d700 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1d710 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1d720 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1d730 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1d740 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1d750 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1d760 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1d770 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
1d780 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1d790 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1d7a0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1d7b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1d7c0 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
1d7d0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1d7e0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1d7f0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1d800 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1d810 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1d820 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1d830 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1d840 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1d850 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1d860 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1d870 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1d880 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1d890 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1d8a0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1d8b0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1d8c0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1d8d0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1d8e0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1d8f0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
1d900 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
1d910 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
1d920 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  t SQL.**.** ^Thi
1d930 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1d940 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
1d950 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
1d960 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
1d970 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
1d980 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
1d990 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d9a0 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
1d9b0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
1d9c0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
1d9d0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1d9e0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
1d9f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1da00 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  2()]..*/.const c
1da10 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
1da20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
1da30 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
1da40 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
1da50 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
1da60 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
1da70 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
1da80 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
1da90 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1daa0 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
1dab0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
1dac0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1dad0 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
1dae0 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
1daf0 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
1db00 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
1db10 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
1db20 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
1db30 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
1db40 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
1db50 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
1db60 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
1db70 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
1db80 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
1db90 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
1dba0 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
1dbb0 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
1dbc0 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
1dbd0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
1dbe0 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
1dbf0 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
1dc00 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
1dc10 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
1dc20 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
1dc30 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
1dc40 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
1dc50 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
1dc60 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
1dc70 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
1dc80 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1dc90 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
1dca0 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
1dcb0 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
1dcc0 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
1dcd0 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
1dce0 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
1dcf0 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
1dd00 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
1dd10 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
1dd20 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
1dd30 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
1dd40 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
1dd50 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
1dd60 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e   held.  A intern
1dd70 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
1dd80 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
1dd90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1dda0 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
1ddb0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1ddc0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
1ddd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1dde0 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
1ddf0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1de00 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
1de10 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
1de20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1de30 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
1de40 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1de50 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
1de60 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
1de70 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
1de80 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
1de90 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
1dea0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
1deb0 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
1dec0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
1ded0 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
1dee0 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
1def0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
1df00 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1df10 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1df20 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1df30 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
1df40 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
1df50 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
1df60 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
1df70 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
1df80 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
1df90 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
1dfa0 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
1dfb0 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
1dfc0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74  tion between bet
1dfd0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
1dfe0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
1dff0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1e000 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
1e010 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
1e020 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
1e030 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
1e040 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
1e050 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
1e060 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
1e070 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1e080 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
1e090 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
1e0a0 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
1e0b0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
1e0c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1e0d0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
1e0e0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
1e0f0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
1e100 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
1e110 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
1e120 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e130 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
1e140 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
1e150 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
1e160 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1e170 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
1e180 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1e190 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
1e1a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
1e1b0 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
1e1c0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
1e1d0 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
1e1e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e1f0 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
1e200 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
1e210 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
1e220 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
1e230 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
1e240 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
1e250 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
1e260 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
1e270 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
1e280 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
1e290 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
1e2a0 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65  ject.  ^A pointe
1e2b0 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
1e2c0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
1e2d0 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
1e2e0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
1e2f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1e300 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1e310 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
1e320 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1e330 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
1e340 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
1e350 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
1e360 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
1e370 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
1e380 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
1e390 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
1e3a0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1e3b0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
1e3c0 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
1e3d0 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
1e3e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
1e3f0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
1e400 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
1e410 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
1e420 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
1e430 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
1e440 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1e450 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
1e460 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
1e470 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
1e480 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
1e490 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
1e4a0 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ents.** KEYWORDS
1e4b0 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  : {host paramete
1e4c0 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  r} {host paramet
1e4d0 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ers} {host param
1e4e0 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45  eter name}.** KE
1e4f0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72  YWORDS: {SQL par
1e500 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72  ameter} {SQL par
1e510 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65  ameters} {parame
1e520 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a  ter binding}.**.
1e530 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
1e540 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
1e550 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1e560 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1e570 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
1e580 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
1e590 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
1e5a0 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
1e5b0 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
1e5c0 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
1e5d0 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
1e5e0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
1e5f0 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
1e600 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
1e610 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
1e620 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
1e630 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
1e640 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
1e650 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
1e660 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
1e670 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
1e680 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
1e690 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 65  numeric identife
1e6a0 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
1e6b0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
1e6c0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
1e6d0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
1e6e0 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
1e6f0 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
1e700 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
1e710 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
1e720 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
1e730 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
1e740 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1e750 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1e760 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1e770 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
1e780 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
1e790 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
1e7a0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
1e7b0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
1e7c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1e7d0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
1e7e0 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
1e7f0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
1e800 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
1e810 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
1e820 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
1e830 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
1e840 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
1e850 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
1e860 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
1e870 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
1e880 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
1e890 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
1e8a0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
1e8b0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
1e8c0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
1e8d0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
1e8e0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
1e8f0 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
1e900 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
1e910 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
1e920 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
1e930 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
1e940 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1e950 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
1e960 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
1e970 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
1e980 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
1e990 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
1e9a0 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
1e9b0 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
1e9c0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
1e9d0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1e9e0 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
1e9f0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1ea00 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
1ea10 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
1ea20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
1ea30 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
1ea40 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
1ea50 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
1ea60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
1ea70 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
1ea80 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
1ea90 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
1eaa0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
1eab0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
1eac0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
1ead0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
1eae0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
1eaf0 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
1eb00 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
1eb10 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
1eb20 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1eb30 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
1eb40 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1eb50 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
1eb60 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
1eb70 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
1eb80 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1eb90 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
1eba0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
1ebb0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
1ebc0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
1ebd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1ebe0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
1ebf0 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
1ec00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1ec10 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
1ec20 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
1ec30 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
1ec40 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
1ec50 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
1ec60 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
1ec70 74 2e 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  t. ^If the fifth
1ec80 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
1ec90 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
1eca0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
1ecb0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
1ecc0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
1ecd0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
1ece0 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
1ecf0 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
1ed00 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
1ed10 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
1ed20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
1ed30 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
1ed40 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
1ed50 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
1ed60 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
1ed70 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
1ed80 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
1ed90 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
1eda0 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
1edb0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
1edc0 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
1edd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
1ede0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
1edf0 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
1ee00 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
1ee10 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
1ee20 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
1ee30 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
1ee40 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
1ee50 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
1ee60 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
1ee70 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
1ee80 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
1ee90 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
1eea0 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
1eeb0 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
1eec0 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
1eed0 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
1eee0 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
1eef0 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
1ef00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
1ef10 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
1ef20 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
1ef30 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
1ef40 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
1ef50 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
1ef60 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
1ef70 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
1ef80 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
1ef90 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1efa0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
1efb0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1efc0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
1efd0 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
1efe0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
1eff0 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
1f000 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
1f010 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
1f020 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
1f030 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
1f040 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
1f050 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
1f060 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
1f070 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
1f080 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
1f090 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
1f0a0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
1f0b0 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
1f0c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1f0d0 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
1f0e0 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
1f0f0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
1f100 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
1f110 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
1f120 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
1f130 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
1f140 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1f150 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
1f160 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
1f170 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
1f180 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
1f190 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
1f1a0 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
1f1b0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1f1c0 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
1f1d0 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
1f1e0 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
1f1f0 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
1f200 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
1f210 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
1f220 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
1f230 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
1f240 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
1f250 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
1f260 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
1f270 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
1f280 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1f290 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1f2a0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
1f2b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1f2c0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
1f2d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1f2e0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1f2f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1f300 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
1f310 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1f320 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
1f330 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1f340 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1f350 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
1f360 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
1f370 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
1f380 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
1f390 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1f3a0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
1f3b0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
1f3c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1f3d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
1f3e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1f3f0 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
1f400 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
1f410 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1f420 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
1f430 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
1f440 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1f450 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1f460 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1f470 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1f480 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
1f490 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
1f4a0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
1f4b0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
1f4c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1f4d0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
1f4e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
1f4f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1f500 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
1f510 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
1f520 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f530 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
1f540 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
1f550 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1f560 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
1f570 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
1f580 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
1f590 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
1f5a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1f5b0 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
1f5c0 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
1f5d0 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
1f5e0 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
1f5f0 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
1f600 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
1f610 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
1f620 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
1f630 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
1f640 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
1f650 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
1f660 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
1f670 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
1f680 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
1f690 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
1f6a0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
1f6b0 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
1f6c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
1f6d0 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
1f6e0 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
1f6f0 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
1f700 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
1f710 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
1f720 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
1f730 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
1f740 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
1f750 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
1f760 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
1f770 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
1f780 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1f790 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
1f7a0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
1f7b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1f7c0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
1f7d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1f7e0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1f7f0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1f800 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1f810 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
1f820 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
1f830 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
1f840 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
1f850 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
1f860 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1f870 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
1f880 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1f890 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
1f8a0 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
1f8b0 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
1f8c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f8d0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
1f8e0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
1f8f0 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
1f900 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
1f910 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
1f920 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
1f930 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
1f940 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
1f950 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
1f960 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
1f970 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
1f980 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
1f990 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
1f9a0 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
1f9b0 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
1f9c0 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
1f9d0 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
1f9e0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
1f9f0 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
1fa00 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
1fa10 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
1fa20 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
1fa30 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
1fa40 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
1fa50 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
1fa60 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
1fa70 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
1fa80 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
1fa90 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
1faa0 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
1fab0 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
1fac0 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
1fad0 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
1fae0 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
1faf0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
1fb00 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
1fb10 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
1fb20 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
1fb30 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
1fb40 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
1fb50 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
1fb60 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
1fb70 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
1fb80 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
1fb90 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1fba0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
1fbb0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1fbc0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1fbd0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
1fbe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1fbf0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1fc00 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1fc10 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1fc20 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
1fc30 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1fc40 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1fc50 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
1fc60 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
1fc70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
1fc80 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
1fc90 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
1fca0 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   Name.**.** ^Ret
1fcb0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
1fcc0 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
1fcd0 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
1fce0 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
1fcf0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1fd00 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
1fd10 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
1fd20 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
1fd30 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
1fd40 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1fd50 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
1fd60 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
1fd70 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
1fd80 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
1fd90 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
1fda0 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
1fdb0 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
1fdc0 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
1fdd0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
1fde0 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
1fdf0 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
1fe00 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
1fe10 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
1fe20 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1fe30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1fe40 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
1fe50 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1fe60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1fe70 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
1fe80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1fe90 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
1fea0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1feb0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1fec0 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
1fed0 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
1fee0 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
1fef0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
1ff00 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
1ff10 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
1ff20 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  ment.**.** ^Cont
1ff30 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
1ff40 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
1ff50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1ff60 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
1ff70 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
1ff80 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
1ff90 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
1ffa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1ffb0 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
1ffc0 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
1ffd0 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
1ffe0 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  rs to NULL..*/.i
1fff0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
20000 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
20010 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
20020 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
20030 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
20040 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
20050 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
20060 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
20070 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
20080 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
20090 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
200a0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69  statement]. ^Thi
200b0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
200c0 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20  s 0 if pStmt is 
200d0 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  an SQL.** statem
200e0 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
200f0 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
20100 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
20110 50 44 41 54 45 5d 29 2e 0a 2a 2f 0a 69 6e 74 20  PDATE])..*/.int 
20120 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
20130 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
20140 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
20150 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
20160 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
20170 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
20180 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
20190 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
201a0 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
201b0 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
201c0 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
201d0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
201e0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
201f0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
20200 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
20210 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
20220 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
20230 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
20240 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
20250 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20260 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
20270 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
20280 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
20290 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
202a0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
202b0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
202c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
202d0 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
202e0 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
202f0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
20300 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
20310 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
20320 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
20330 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
20340 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
20350 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
20360 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
20370 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
20380 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
20390 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
203a0 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
203b0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
203c0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
203d0 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
203e0 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
203f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
20400 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20410 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
20420 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
20430 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
20440 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
20450 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
20460 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
20470 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
20480 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
20490 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
204a0 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
204b0 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
204c0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
204d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
204e0 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
204f0 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
20500 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
20510 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
20520 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
20530 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
20540 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
20550 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
20560 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
20570 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
20580 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
20590 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
205a0 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
205b0 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
205c0 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
205d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
205e0 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
205f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
20600 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
20610 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
20620 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
20630 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
20640 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
20650 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
20660 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
20670 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
20680 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
20690 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
206a0 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
206b0 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
206c0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
206d0 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
206e0 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
206f0 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
20700 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
20710 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
20720 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
20730 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
20740 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
20750 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
20760 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
20770 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
20780 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
20790 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
207a0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
207b0 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
207c0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
207d0 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
207e0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
207f0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
20800 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
20810 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
20820 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
20830 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
20840 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20850 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
20860 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
20870 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
20880 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
20890 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
208a0 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
208b0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
208c0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
208d0 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
208e0 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
208f0 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
20900 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
20910 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
20920 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
20930 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
20940 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
20950 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
20960 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20970 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
20980 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
20990 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
209a0 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
209b0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
209c0 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
209d0 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
209e0 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
209f0 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
20a00 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
20a10 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
20a20 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
20a30 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
20a40 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
20a50 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
20a60 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
20a70 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
20a80 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
20a90 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
20aa0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
20ab0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
20ac0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
20ad0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
20ae0 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
20af0 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
20b00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
20b10 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
20b20 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
20b30 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
20b40 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
20b50 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
20b60 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
20b70 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
20b80 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
20b90 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
20ba0 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
20bb0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
20bc0 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
20bd0 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
20be0 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
20bf0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
20c00 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
20c10 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
20c20 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
20c30 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
20c40 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
20c50 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
20c60 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
20c70 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
20c80 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
20c90 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
20ca0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
20cb0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
20cc0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
20cd0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
20ce0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
20cf0 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
20d00 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
20d10 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
20d20 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
20d30 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
20d40 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
20d50 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
20d60 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
20d70 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
20d80 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
20d90 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
20da0 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
20db0 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
20dc0 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
20dd0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
20de0 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
20df0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
20e00 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
20e10 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
20e20 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
20e30 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
20e40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
20e50 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
20e60 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
20e70 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
20e80 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
20e90 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
20ea0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
20eb0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
20ec0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
20ed0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
20ee0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
20ef0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
20f00 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
20f10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
20f20 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
20f30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
20f40 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
20f50 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
20f60 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
20f70 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
20f80 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
20f90 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
20fa0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
20fb0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
20fc0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
20fd0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
20fe0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
20ff0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21000 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
21010 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
21020 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
21030 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
21040 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
21050 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
21060 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
21070 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
21080 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
21090 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
210a0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
210b0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
210c0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
210d0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
210e0 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
210f0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
21100 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
21110 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
21120 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
21130 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
21140 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
21150 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
21160 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
21170 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
21180 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
21190 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
211a0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
211b0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
211c0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
211d0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
211e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
211f0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
21200 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
21210 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
21220 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
21230 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
21240 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
21250 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
21260 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
21270 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
21280 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
21290 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
212a0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
212b0 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
212c0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
212d0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
212e0 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
212f0 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
21300 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
21310 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
21320 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
21330 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
21340 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
21350 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
21360 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
21370 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
21380 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
21390 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
213a0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
213b0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
213c0 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
213d0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
213e0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
213f0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
21400 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
21410 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
21420 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
21430 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
21440 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
21450 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
21460 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
21470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
21480 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
21490 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
214a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
214b0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
214c0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74  tement.**.** Aft
214d0 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
214e0 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
214f0 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
21500 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
21510 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21520 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
21530 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
21540 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
21550 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
21560 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
21570 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
21580 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
21590 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
215a0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
215b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
215c0 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
215d0 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
215e0 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
215f0 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
21600 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
21610 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
21620 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
21630 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
21640 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
21650 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
21660 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
21670 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21680 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
21690 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
216a0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
216b0 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
216c0 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
216d0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
216e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
216f0 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
21700 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
21710 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
21720 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
21730 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
21740 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
21750 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
21760 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
21770 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
21780 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
21790 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
217a0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
217b0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
217c0 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
217d0 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
217e0 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
217f0 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
21800 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
21810 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
21820 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
21830 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
21840 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
21850 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
21860 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
21870 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
21880 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
21890 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
218a0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
218b0 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
218c0 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
218d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
218e0 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
218f0 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
21900 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
21910 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
21920 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
21930 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
21940 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
21950 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
21960 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
21970 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
21980 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
21990 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
219a0 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70   within a.** exp
219b0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
219c0 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
219d0 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
219e0 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
219f0 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
21a00 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
21a10 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
21a20 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
21a30 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
21a40 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
21a50 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
21a60 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
21a70 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
21a80 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
21a90 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
21aa0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
21ab0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
21ac0 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
21ad0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
21ae0 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
21af0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
21b00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
21b10 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
21b20 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
21b30 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
21b40 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
21b50 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
21b60 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
21b70 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
21b80 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
21b90 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
21ba0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
21bb0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
21bc0 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
21bd0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
21be0 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
21bf0 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
21c00 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
21c10 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
21c20 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
21c30 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
21c40 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
21c50 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
21c60 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
21c70 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
21c80 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
21c90 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
21ca0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
21cb0 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
21cc0 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
21cd0 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
21ce0 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
21cf0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
21d00 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
21d10 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
21d20 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
21d30 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
21d40 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
21d50 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
21d60 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
21d70 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
21d80 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
21d90 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
21da0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
21db0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
21dc0 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
21dd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21de0 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
21df0 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
21e00 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
21e10 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
21e20 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
21e30 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
21e40 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
21e50 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
21e60 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
21e70 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
21e80 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
21e90 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
21ea0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
21eb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21ec0 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
21ed0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
21ee0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
21ef0 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
21f00 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
21f10 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
21f20 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
21f30 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
21f40 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
21f50 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
21f60 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
21f70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21f80 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
21f90 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
21fa0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
21fb0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
21fc0 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
21fd0 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
21fe0 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
21ff0 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
22000 36 2e 32 33 2e 31 2c 20 69 74 20 77 61 73 20 72  6.23.1, it was r
22010 65 71 75 69 72 65 64 0a 2a 2a 20 61 66 74 65 72  equired.** after
22020 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
22030 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
22040 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
22050 4c 49 54 45 5f 52 4f 57 5d 20 74 68 61 74 0a 2a  LITE_ROW] that.*
22060 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
22070 28 29 5d 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ()] be called be
22080 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
22090 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
220a0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
220b0 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
220c0 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
220d0 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 74 68 69  _reset()] in thi
220e0 73 20 77 61 79 20 77 6f 75 6c 64 0a 2a 2a 20 72  s way would.** r
220f0 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
22100 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
22110 72 6e 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  rn from sqlite3_
22120 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
22130 65 72 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e  er.** version 3.
22140 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
22150 73 74 65 70 28 29 20 62 65 67 61 6e 20 63 61 6c  step() began cal
22160 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
22170 73 65 74 28 29 5d 20 0a 2a 2a 20 61 75 74 6f 6d  set()] .** autom
22180 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
22190 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
221a0 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e  ther than return
221b0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
221c0 53 45 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e  SE].  .**.** <b>
221d0 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
221e0 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
221f0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
22200 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
22210 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
22220 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
22230 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
22240 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
22250 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
22260 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
22270 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
22280 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
22290 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
222a0 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
222b0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
222c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
222d0 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
222e0 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
222f0 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
22300 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
22310 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
22320 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
22330 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
22340 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
22350 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
22360 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
22370 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
22380 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
22390 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
223a0 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
223b0 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
223c0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
223d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
223e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
223f0 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
22400 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
22410 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
22420 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
22430 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
22440 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
22450 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
22460 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
22470 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
22480 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
22490 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
224a0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
224b0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
224c0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
224d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
224e0 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
224f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
22500 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
22510 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
22520 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt set.**.** ^Th
22530 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
22540 6f 75 6e 74 28 50 29 20 74 68 65 20 6e 75 6d 62  ount(P) the numb
22550 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
22560 20 74 68 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72   the.** of the r
22570 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
22580 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22590 5d 20 50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] P..*/.int sqli
225a0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
225b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
225c0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
225d0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
225e0 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
225f0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
22600 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
22610 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
22620 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
22630 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
22640 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
22650 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
22660 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
22670 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
22680 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
22690 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
226a0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
226b0 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
226c0 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
226d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
226e0 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
226f0 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
22700 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
22710 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
22720 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
22730 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
22740 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
22750 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
22760 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
22770 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
22780 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
22790 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
227a0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
227b0 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
227c0 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
227d0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
227e0 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
227f0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
22800 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
22810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22820 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
22830 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
22840 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
22850 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
22860 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
22870 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
22880 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
22890 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
228a0 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
228b0 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
228c0 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
228d0 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
228e0 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
228f0 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
22900 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
22910 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
22920 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
22930 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c   form the "resul
22940 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65  t set" interface
22950 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
22960 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
22970 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
22980 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
22990 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
229a0 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
229b0 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
229c0 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
229d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
229e0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
229f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
22a00 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
22a10 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
22a20 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
22a30 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
22a40 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
22a50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22a60 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
22a70 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
22a80 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
22a90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
22aa0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
22ab0 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
22ac0 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
22ad0 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
22ae0 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
22af0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
22b00 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
22b10 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
22b20 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
22b30 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
22b40 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
22b50 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
22b60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
22b70 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
22b80 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
22b90 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
22ba0 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
22bb0 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
22bc0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
22bd0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
22be0 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
22bf0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
22c00 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
22c10 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
22c20 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
22c30 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
22c40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
22c50 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
22c60 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
22c70 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
22c80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
22c90 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
22ca0 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
22cb0 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
22cc0 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
22cd0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
22ce0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
22cf0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
22d00 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
22d10 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
22d20 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
22d30 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
22d40 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
22d50 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
22d60 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
22d70 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
22d80 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
22d90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22da0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
22db0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
22dc0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
22dd0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
22de0 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
22df0 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
22e00 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
22e10 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
22e20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
22e30 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
22e40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
22e50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
22e60 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
22e70 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
22e80 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
22e90 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
22ea0 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
22eb0 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
22ec0 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
22ed0 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
22ee0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
22ef0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
22f00 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
22f10 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
22f20 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
22f30 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
22f40 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
22f50 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
22f60 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
22f70 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
22f80 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
22f90 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
22fa0 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
22fb0 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
22fc0 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
22fd0 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
22fe0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
22ff0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
23000 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
23010 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
23020 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
23030 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
23040 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
23050 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
23060 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
23070 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
23080 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
23090 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
230a0 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
230b0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
230c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
230d0 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
230e0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
230f0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
23100 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
23110 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
23120 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
23130 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
23140 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
23150 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
23160 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
23170 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
23180 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
23190 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
231a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
231b0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
231c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
231d0 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
231e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
231f0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
23200 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
23210 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
23220 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
23230 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
23240 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
23250 6e 67 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  ng..** ^The valu
23260 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  e returned does 
23270 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
23280 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
23290 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
232a0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
232b0 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
232c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
232d0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
232e0 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
232f0 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
23300 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
23310 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
23320 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
23330 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23340 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
23350 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
23360 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
23370 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
23380 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69  lways zero termi
23390 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
233a0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
233b0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
233c0 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
233d0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
233e0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a  s an arbitrary.*
233f0 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69  * pointer, possi
23400 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20  bly even a NULL 
23410 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
23420 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
23430 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75  mn_bytes16() rou
23440 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
23450 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
23460 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74  n_bytes().** but
23470 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75   leaves the resu
23480 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20  lt in UTF-16 in 
23490 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
234a0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46  r instead of UTF
234b0 2d 38 2e 0a 2a 2a 20 5e 54 68 65 20 7a 65 72 6f  -8..** ^The zero
234c0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e   terminator is n
234d0 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ot included in t
234e0 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a  his count..**.**
234f0 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
23500 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
23510 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
23520 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
23530 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23540 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
23550 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
23560 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
23570 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
23580 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
23590 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
235a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
235b0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
235c0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
235d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
235e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
235f0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
23600 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
23610 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
23620 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
23630 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
23640 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
23650 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
23660 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
23670 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
23680 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
23690 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
236a0 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
236b0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
236c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
236d0 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
236e0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
236f0 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
23700 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
23710 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
23720 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
23730 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
23740 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
23750 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
23760 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
23770 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
23780 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
23790 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
237a0 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
237b0 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
237c0 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
237d0 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
237e0 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
237f0 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
23800 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
23810 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
23820 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
23830 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
23840 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
23850 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
23860 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
23870 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
23880 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
23890 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
238a0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
238b0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
238c0 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
238d0 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
238e0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
238f0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
23900 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
23910 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
23920 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
23930 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
23940 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
23950 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
23960 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
23970 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
23980 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
23990 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
239a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
239b0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
239c0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
239d0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
239e0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
239f0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
23a00 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
23a10 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
23a20 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
23a30 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
23a40 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
23a50 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
23a60 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
23a70 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
23a80 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
23a90 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
23aa0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
23ab0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
23ac0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
23ad0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
23ae0 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
23af0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
23b00 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
23b10 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
23b20 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
23b30 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
23b40 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
23b50 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
23b60 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
23b70 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
23b80 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
23b90 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
23ba0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
23bb0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
23bc0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
23bd0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
23be0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
23bf0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
23c00 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
23c10 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
23c20 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
23c30 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
23c40 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
23c50 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
23c60 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
23c70 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
23c80 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
23c90 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
23ca0 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
23cb0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
23cc0 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
23cd0 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
23ce0 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
23cf0 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
23d00 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
23d10 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
23d20 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
23d30 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
23d40 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
23d50 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
23d60 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
23d70 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
23d80 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
23d90 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
23da0 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
23db0 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
23dc0 20 5e 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e   ^Note that when
23dd0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
23de0 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
23df0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
23e00 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
23e10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23e20 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
23e30 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
23e40 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
23e50 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
23e60 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
23e70 65 64 2e 0a 2a 2a 20 5e 28 54 79 70 65 20 63 6f  ed..** ^(Type co
23e80 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
23e90 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
23ea0 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
23eb0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
23ec0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
23ed0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
23ee0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
23ef0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
23f00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23f10 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
23f20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23f30 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
23f40 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
23f50 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
23f60 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
23f70 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
23f80 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
23f90 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
23fa0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
23fb0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
23fc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
23fd0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
23fe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
23ff0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
24000 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
24010 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
24020 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
24030 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
24040 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
24050 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
24060 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
24070 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
24080 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
24090 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
240a0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
240b0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
240c0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
240d0 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
240e0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   </ul>)^.**.** ^
240f0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
24100 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
24110 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
24120 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
24130 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
24140 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
24150 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
24160 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
24170 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
24180 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
24190 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
241a0 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c  r points to will
241b0 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
241c0 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
241d0 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
241e0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
241f0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
24200 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
24210 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
24220 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
24230 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
24240 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
24250 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
24260 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ed..**.** ^(The 
24270 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
24280 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
24290 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
242a0 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
242b0 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
242c0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
242d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
242e0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
242f0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
24300 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
24310 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
24320 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
24330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
24340 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
24350 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24360 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
24370 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
24380 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
24390 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
243a0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
243b0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  li>.** </ul>)^.*
243c0 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
243d0 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
243e0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
243f0 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
24400 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
24410 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
24420 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
24430 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
24440 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
24450 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
24460 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
24470 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
24480 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
24490 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
244a0 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
244b0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
244c0 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
244d0 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
244e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
244f0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
24500 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
24510 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
24520 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24530 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
24540 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
24550 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
24560 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
24570 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
24580 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24590 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
245a0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
245b0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
245c0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
245d0 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
245e0 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
245f0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
24600 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
24610 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
24620 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
24630 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
24640 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
24650 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
24660 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
24670 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
24680 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
24690 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
246a0 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
246b0 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
246c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
246d0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
246e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
246f0 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
24700 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
24710 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
24720 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
24730 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
24740 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
24750 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
24760 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
24770 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
24780 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
24790 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
247a0 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
247b0 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
247c0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
247d0 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
247e0 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
247f0 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
24800 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
24810 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
24820 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
24830 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f  _NOMEM].)^.*/.co
24840 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
24850 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
24860 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24870 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
24880 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24890 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
248a0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
248b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
248c0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
248d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
248e0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
248f0 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
24900 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
24910 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
24920 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
24930 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24940 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
24950 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
24960 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
24970 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24980 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
24990 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
249a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
249b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
249c0 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
249d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
249e0 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
249f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
24a00 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
24a10 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
24a20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
24a30 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
24a40 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
24a50 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
24a60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
24a70 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
24a80 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
24a90 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
24aa0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e  t Object.**.** ^
24ab0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
24ac0 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
24ad0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
24ae0 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
24af0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
24b00 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
24b10 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73 75   was executed su
24b20 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f  ccessfully or no
24b30 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c  t executed at al
24b40 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54  l, then.** SQLIT
24b50 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
24b60 2e 20 5e 49 66 20 65 78 65 63 75 74 69 6f 6e 20  . ^If execution 
24b70 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
24b80 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a   failed then an.
24b90 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
24ba0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
24bb0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
24bc0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rned..**.** ^Thi
24bd0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
24be0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
24bf0 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20  oint during the 
24c00 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
24c10 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
24c20 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 66 20 74  atement].  ^If t
24c30 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69  he virtual machi
24c40 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f  ne has not.** co
24c50 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
24c60 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74  n when this rout
24c70 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  ine is called, t
24c80 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65  hat is like.** e
24c90 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65  ncountering an e
24ca0 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  rror or an [sqli
24cb0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20  te3_interrupt | 
24cc0 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 5e  interrupt]..** ^
24cd0 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74  Incomplete updat
24ce0 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64  es may be rolled
24cf0 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61   back and transa
24d00 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c  ctions canceled,
24d10 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  .** depending on
24d20 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63   the circumstanc
24d30 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b  es, and the.** [
24d40 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75  error code] retu
24d50 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51  rned will be [SQ
24d60 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a  LITE_ABORT]..*/.
24d70 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
24d80 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
24d90 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
24da0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
24db0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
24dc0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
24dd0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
24de0 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
24df0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
24e00 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
24e10 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
24e20 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
24e30 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
24e40 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
24e50 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
24e60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
24e70 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
24e80 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
24e90 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
24ea0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
24eb0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
24ec0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
24ed0 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
24ee0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
24ef0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
24f00 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
24f10 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
24f20 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
24f30 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
24f40 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
24f50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24f60 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
24f70 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
24f80 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
24f90 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
24fa0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
24fb0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
24fc0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
24fd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24fe0 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
24ff0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
25000 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
25010 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
25020 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
25030 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
25040 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
25050 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
25060 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
25070 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
25080 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
25090 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
250a0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
250b0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
250c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
250d0 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
250e0 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
250f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
25100 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
25110 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
25120 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
25130 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
25140 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
25150 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
25160 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
25170 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
25180 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
25190 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
251a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
251b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
251c0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
251d0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
251e0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
251f0 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
25200 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
25210 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
25220 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
25230 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
25240 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
25250 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
25260 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
25270 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
25280 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
25290 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
252a0 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ese two function
252b0 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
252c0 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
252d0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
252e0 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
252f0 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
25300 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
25310 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
25320 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
25330 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
25340 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
25350 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
25360 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
25370 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a  ce between the.*
25380 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68  * two is that th
25390 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
253a0 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  er, the name of 
253b0 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e  the (scalar) fun
253c0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
253d0 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65  egate, is encode
253e0 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73  d in UTF-8 for s
253f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
25400 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46  nction() and UTF
25410 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  -16.** for sqlit
25420 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
25430 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  on16()..**.** ^T
25440 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
25450 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
25460 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
25470 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
25480 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
25490 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
254a0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
254b0 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
254c0 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
254d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
254e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
254f0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
25500 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
25510 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
25520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
25530 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
25540 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
25550 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
25560 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
25570 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
25580 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
25590 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
255a0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
255b0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
255c0 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65  bytes, exclusive
255d0 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d   of.** the zero-
255e0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74  terminator.  Not
255f0 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20  e that the name 
25600 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
25610 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a  in bytes, not.**
25620 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 5e 41   characters.  ^A
25630 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
25640 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
25650 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
25660 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
25670 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  t in [SQLITE_ERR
25680 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  OR] being return
25690 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
256a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
256b0 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
256c0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
256d0 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
256e0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
256f0 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
25700 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
25710 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
25720 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
25730 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
25740 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
25750 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
25760 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
25770 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
25780 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
25790 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
257a0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
257b0 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
257c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
257d0 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
257e0 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
257f0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
25800 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
25810 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ed..**.** The fo
25820 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
25830 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
25840 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
25850 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
25860 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
25870 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
25880 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
25890 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20  arameters.  Any 
258a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
258b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
258c0 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  ld be able to wo
258d0 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20  rk.** work with 
258e0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
258f0 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
25900 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
25910 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
25920 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
25930 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
25940 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
25950 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
25960 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
25970 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25980 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
25990 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
259a0 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
259b0 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
259c0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
259d0 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
259e0 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
259f0 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65  TextRep..** ^Whe
25a00 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
25a10 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
25a20 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
25a30 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
25a40 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
25a50 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
25a60 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
25a70 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
25a80 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
25a90 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
25aa0 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
25ab0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
25ac0 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
25ad0 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
25ae0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
25af0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
25b00 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
25b10 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
25b20 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
25b30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
25b40 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
25b50 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
25b60 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
25b70 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
25b80 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
25b90 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
25ba0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
25bb0 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  ta()].)^.**.** T
25bc0 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68  he seventh, eigh
25bd0 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72  th and ninth par
25be0 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
25bf0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
25c00 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
25c10 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
25c20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
25c30 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
25c40 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
25c50 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63  aggregate. ^A sc
25c60 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
25c70 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
25c80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
25c90 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
25ca0 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c  lback only; NULL
25cb0 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64   pointers should
25cc0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
25cd0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
25ce0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
25cf0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
25d00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
25d10 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
25d20 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
25d30 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
25d40 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62  nd NULL should b
25d50 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
25d60 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
25d70 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
25d80 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
25d90 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
25da0 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  LL for all three
25db0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
25dc0 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  cks..**.** ^It i
25dd0 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
25de0 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
25df0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
25e00 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
25e10 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
25e20 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
25e30 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
25e40 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
25e50 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
25e60 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
25e70 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
25e80 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
25e90 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
25ea0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
25eb0 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
25ec0 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
25ed0 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
25ee0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
25ef0 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
25f00 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
25f10 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
25f20 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
25f30 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
25f40 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
25f50 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
25f60 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
25f70 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
25f80 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
25f90 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
25fa0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
25fb0 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
25fc0 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
25fd0 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
25fe0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
25ff0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
26000 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
26010 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
26020 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
26030 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
26040 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
26050 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
26060 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
26070 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
26080 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
26090 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
260a0 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
260b0 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
260c0 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
260d0 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
260e0 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
260f0 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
26100 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26110 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 5e 54 68 65  nctions..** ^The
26120 20 66 69 72 73 74 20 61 70 70 6c 69 63 61 74 69   first applicati
26130 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
26140 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e  ion with a given
26150 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20   name overrides 
26160 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20  all.** built-in 
26170 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65  functions in the
26180 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
26190 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68  connection] with
261a0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a   the same name..
261b0 2a 2a 20 5e 53 75 62 73 65 71 75 65 6e 74 20 61  ** ^Subsequent a
261c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
261d0 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20  ed functions of 
261e0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e  the same name on
261f0 6c 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20  ly override .** 
26200 70 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f  prior applicatio
26210 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
26220 6f 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e 20  ons that are an 
26230 65 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20  exact match for 
26240 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
26250 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
26260 70 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69  preferred encodi
26270 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ng..**.** ^An ap
26280 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26290 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
262a0 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
262b0 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
262c0 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
262d0 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
262e0 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
262f0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
26300 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
26310 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
26320 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
26330 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
26340 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
26350 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
26360 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
26370 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
26380 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
26390 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
263a0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
263b0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
263c0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
263d0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
263e0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
263f0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
26400 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
26410 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
26420 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
26430 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
26440 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
26450 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
26460 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
26470 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
26480 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
26490 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
264a0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
264b0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
264c0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
264d0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
264e0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
264f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
26500 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
26510 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
26520 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
26530 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
26540 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
26550 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
26560 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
26570 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26580 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
26590 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
265a0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
265b0 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
265c0 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
265d0 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
265e0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
265f0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
26600 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
26610 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
26620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
26630 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
26640 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
26650 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
26660 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
26670 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
26680 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
26690 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
266a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
266b0 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
266c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
266d0 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
266e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
266f0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
26700 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
26710 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
26720 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
26730 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
26740 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
26750 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
26760 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
26770 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
26780 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
26790 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
267a0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
267b0 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
267c0 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
267d0 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
267e0 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
267f0 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
26800 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
26810 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
26820 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
26830 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
26840 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
26850 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
26860 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
26870 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
26880 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
26890 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65  ell you what the
268a0 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
268b0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
268c0 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
268d0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
268e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
268f0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
26900 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
26910 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
26920 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
26930 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
26940 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
26950 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
26960 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
26970 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
26980 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
26990 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
269a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
269b0 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
269c0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
269d0 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
269e0 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
269f0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
26a00 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
26a10 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
26a20 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
26a30 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
26a40 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  t),void*,sqlite3
26a50 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
26a60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26a70 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
26a80 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
26a90 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
26aa0 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
26ab0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
26ac0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
26ad0 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
26ae0 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
26af0 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
26b00 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
26b10 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
26b20 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
26b30 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
26b40 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
26b50 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
26b60 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
26b70 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
26b80 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
26b90 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
26ba0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
26bb0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
26bc0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
26bd0 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
26be0 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
26bf0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
26c00 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
26c10 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
26c20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
26c30 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
26c40 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
26c50 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
26c60 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26c70 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
26c80 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
26c90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
26ca0 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
26cb0 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
26cc0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
26cd0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
26ce0 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
26cf0 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
26d00 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
26d10 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
26d20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
26d30 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
26d40 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
26d50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
26d60 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
26d70 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
26d80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
26d90 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
26da0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
26db0 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
26dc0 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
26dd0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
26de0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
26df0 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
26e00 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
26e10 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
26e20 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
26e30 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20  ept that  these 
26e40 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
26e50 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
26e60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
26e70 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
26e80 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
26e90 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
26ea0 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
26eb0 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
26ec0 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
26ed0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
26ee0 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
26ef0 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
26f00 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
26f10 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
26f20 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
26f30 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
26f40 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
26f50 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
26f60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
26f70 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
26f80 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
26f90 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
26fa0 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
26fb0 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
26fc0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
26fd0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
26fe0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
26ff0 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
27000 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
27010 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
27020 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
27030 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
27040 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
27050 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
27060 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
27070 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
27080 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
27090 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
270a0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
270b0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
270c0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
270d0 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
270e0 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
270f0 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
27100 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
27110 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
27120 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
27130 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
27140 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
27150 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
27160 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
27170 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
27180 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
27190 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
271a0 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
271b0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
271c0 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
271d0 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
271e0 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
271f0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
27200 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
27210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27220 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
27230 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
27240 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
27250 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
27260 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
27270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
27280 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
27290 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
272a0 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
272b0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
272c0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
272d0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
272e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
272f0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
27300 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
27310 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
27320 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
27330 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
27340 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
27350 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
27360 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
27370 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
27380 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
27390 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
273a0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
273b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
273c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
273d0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
273e0 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
273f0 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
27400 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
27410 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
27420 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
27430 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
27440 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
27450 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
27460 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
27470 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
27480 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
27490 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
274a0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
274b0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
274c0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
274d0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
274e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
274f0 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
27500 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
27510 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
27520 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
27530 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27540 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
27550 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
27560 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
27570 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
27580 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
27590 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
275a0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
275b0 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
275c0 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  on Context.**.**
275d0 20 49 6d 70 6c 65 6d 65 6e 74 69 6f 6e 73 20 6f   Implementions o
275e0 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
275f0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
27600 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
27610 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
27620 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
27630 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
27640 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
27650 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
27660 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
27670 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
27680 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
27690 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
276a0 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
276b0 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
276c0 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
276d0 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
276e0 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
276f0 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
27700 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
27710 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
27720 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
27730 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
27740 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27750 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
27760 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
27770 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
27780 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
27790 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
277a0 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
277b0 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
277c0 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
277d0 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
277e0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
277f0 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
27800 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
27810 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
27820 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
27830 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
27840 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
27850 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
27860 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
27870 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
27880 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
27890 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
278a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
278b0 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
278c0 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
278d0 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
278e0 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
278f0 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
27900 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
27910 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
27920 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
27930 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
27940 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
27950 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27960 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
27970 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
27980 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
27990 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73   pointer if N is
279a0 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  .** less than or
279b0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
279c0 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
279d0 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
279e0 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
279f0 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
27a00 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
27a10 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27a20 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
27a30 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
27a40 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
27a50 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
27a60 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
27a70 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
27a80 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
27a90 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
27aa0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
27ab0 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
27ac0 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
27ad0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
27ae0 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
27af0 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
27b00 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
27b10 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
27b20 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
27b30 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
27b40 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
27b50 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
27b60 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
27b70 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
27b80 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
27b90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
27ba0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
27bb0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
27bc0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
27bd0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
27be0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
27bf0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
27c00 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
27c10 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
27c20 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
27c30 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
27c40 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
27c50 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
27c60 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
27c70 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
27c80 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
27c90 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
27ca0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
27cb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
27cc0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
27cd0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
27ce0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
27cf0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
27d00 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
27d10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
27d20 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
27d30 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
27d40 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
27d50 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
27d60 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
27d70 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
27d80 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
27d90 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
27da0 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
27db0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
27dc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27dd0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
27de0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
27df0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
27e00 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
27e10 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
27e20 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
27e30 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
27e40 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
27e50 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
27e60 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
27e70 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
27e80 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
27e90 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
27ea0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
27eb0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
27ec0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
27ed0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
27ee0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
27ef0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
27f00 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
27f10 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
27f20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
27f30 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
27f40 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27f50 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
27f60 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
27f70 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
27f80 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
27f90 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
27fa0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
27fb0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
27fc0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
27fd0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27fe0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
27ff0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
28000 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
28010 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
28020 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
28030 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
28040 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
28050 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
28060 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
28070 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
28080 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
28090 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  a.**.** The foll
280a0 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
280b0 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
280c0 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  by scalar SQL fu
280d0 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
280e0 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
280f0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
28100 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
28110 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
28120 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
28130 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
28140 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
28150 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
28160 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
28170 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
28180 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
28190 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
281a0 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
281b0 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a  ved. This may.**
281c0 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
281d0 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20  ample, to add a 
281e0 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
281f0 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c  on matching scal
28200 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ar.** function. 
28210 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
28220 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
28230 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69  lar expression i
28240 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  s stored as.** m
28250 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
28260 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
28270 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
28280 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
28290 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
282a0 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
282b0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
282c0 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
282d0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
282e0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
282f0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
28300 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
28310 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
28320 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
28330 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
28340 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
28350 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
28360 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
28370 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
28380 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
28390 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
283a0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
283b0 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
283c0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
283d0 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
283e0 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
283f0 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
28400 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
28410 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
28420 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61   ^If no metadata
28430 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
28440 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
28450 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
28460 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
28470 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
28480 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
28490 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
284a0 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
284b0 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
284c0 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
284d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
284e0 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
284f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
28500 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28510 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
28520 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
28530 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
28540 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
28550 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
28560 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
28570 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
28580 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
28590 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
285a0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
285b0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
285c0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
285d0 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
285e0 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
285f0 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
28600 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
28610 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73  ed..** ^If it is
28620 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
28630 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
28640 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
28650 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62  function given b
28660 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  y the 4th parame
28670 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  ter to sqlite3_s
28680 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a  et_auxdata() on.
28690 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  ** the metadata 
286a0 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
286b0 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
286c0 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
286d0 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
286e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
286f0 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65  ompletes, whiche
28700 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
28710 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  .**.** SQLite is
28720 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68   free to call th
28730 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64  e destructor and
28740 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f   drop metadata o
28750 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74  n any.** paramet
28760 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69  er of any functi
28770 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20  on at any time. 
28780 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61   ^The only guara
28790 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20  ntee is that.** 
287a0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77  the destructor w
287b0 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ill be called be
287c0 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74  fore the metadat
287d0 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  a is dropped..**
287e0 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
287f0 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
28800 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
28810 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
28820 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
28830 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
28840 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
28850 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
28860 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
28870 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
28880 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  eters].)^.**.** 
28890 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
288a0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
288b0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
288c0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
288d0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
288e0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
288f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
28900 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
28910 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
28920 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
28930 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
28940 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
28950 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
28960 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
28970 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28980 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
28990 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
289a0 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
289b0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
289c0 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
289d0 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
289e0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
289f0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
28a00 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
28a10 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
28a20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
28a30 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
28a40 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
28a50 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
28a60 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
28a70 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
28a80 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
28a90 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
28aa0 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
28ab0 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
28ac0 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
28ad0 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
28ae0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
28af0 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
28b00 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
28b10 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
28b20 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
28b30 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
28b40 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
28b50 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
28b60 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
28b70 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
28b80 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
28b90 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
28ba0 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
28bb0 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
28bc0 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
28bd0 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
28be0 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
28bf0 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
28c00 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
28c10 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
28c20 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
28c30 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
28c40 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
28c50 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
28c60 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
28c70 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
28c80 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
28c90 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
28ca0 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
28cb0 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
28cc0 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
28cd0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
28ce0 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
28cf0 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
28d00 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
28d10 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
28d20 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
28d30 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
28d40 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
28d50 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
28d60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
28d70 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
28d80 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
28d90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
28da0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
28db0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
28dc0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
28dd0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
28de0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
28df0 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
28e00 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
28e10 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
28e20 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28e30 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
28e40 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
28e50 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
28e60 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
28e70 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
28e80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28e90 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
28ea0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
28eb0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
28ec0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
28ed0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
28ee0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
28ef0 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
28f00 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
28f10 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
28f20 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
28f30 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
28f40 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
28f50 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
28f60 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
28f70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28f80 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
28f90 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
28fa0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
28fb0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28fc0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
28fd0 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
28fe0 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
28ff0 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
29000 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
29010 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
29020 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
29030 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
29040 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29050 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
29060 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
29070 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
29080 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
29090 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
290a0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
290b0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
290c0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
290d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
290e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
290f0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
29100 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29110 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
29120 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
29130 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
29140 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
29150 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
29160 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
29170 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
29180 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
29190 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
291a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
291b0 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
291c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
291d0 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
291e0 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
291f0 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
29200 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
29210 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
29220 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
29230 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29240 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
29250 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
29260 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
29270 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
29280 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
29290 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
292a0 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
292b0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
292c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
292d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
292e0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
292f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
29300 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
29310 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
29320 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
29330 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
29340 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
29350 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
29360 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
29370 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
29380 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
29390 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
293a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
293b0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
293c0 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
293d0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
293e0 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
293f0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
29400 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
29410 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
29420 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
29430 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29440 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
29450 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29460 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
29470 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
29480 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
29490 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
294a0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
294b0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
294c0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
294d0 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
294e0 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
294f0 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
29500 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
29510 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
29520 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
29530 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
29540 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
29550 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
29560 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
29570 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
29580 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
29590 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
295a0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
295b0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
295c0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
295d0 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
295e0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
295f0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
29600 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
29610 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
29620 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
29630 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
29640 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29650 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
29660 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
29670 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
29680 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
29690 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
296a0 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
296b0 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74  OB is too long t
296c0 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
296d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
296e0 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
296f0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
29700 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
29710 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
29720 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
29730 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
29740 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
29750 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29760 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
29770 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
29780 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
29790 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
297a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
297b0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
297c0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
297d0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
297e0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
297f0 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
29800 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
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 74 75 72 6e 20 76 61 6c 75   the return valu
29830 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
29840 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29850 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
29860 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
29870 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
29880 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
29890 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
298a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
298b0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
298c0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
298d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
298e0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
298f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
29900 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
29910 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29920 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
29930 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
29940 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
29950 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
29960 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
29970 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29980 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
29990 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
299a0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
299b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
299c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
299d0 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
299e0 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
299f0 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
29a00 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
29a10 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
29a20 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
29a30 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
29a40 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
29a50 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
29a60 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
29a70 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
29a80 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
29a90 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
29aa0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
29ab0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29ac0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
29ad0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
29ae0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
29af0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
29b00 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
29b10 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
29b20 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
29b30 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
29b40 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
29b50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
29b60 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
29b70 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
29b80 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
29b90 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
29ba0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29bb0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
29bc0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
29bd0 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
29be0 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
29bf0 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
29c00 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
29c10 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
29c20 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
29c30 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
29c40 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
29c50 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a  ction result..**
29c60 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
29c70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
29c80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29c90 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
29ca0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
29cb0 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
29cc0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
29cd0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
29ce0 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
29cf0 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
29d00 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
29d10 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
29d20 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
29d30 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
29d40 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
29d50 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
29d60 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
29d70 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
29d80 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
29d90 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
29da0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
29db0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
29dc0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
29dd0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
29de0 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
29df0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
29e00 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
29e10 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
29e20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
29e30 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
29e40 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
29e50 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
29e60 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
29e70 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
29e80 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
29e90 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
29ea0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
29eb0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
29ec0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
29ed0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
29ee0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
29ef0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
29f00 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
29f10 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
29f20 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
29f30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
29f40 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
29f50 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
29f60 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
29f70 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
29f80 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
29f90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29fa0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
29fb0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
29fc0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
29fd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
29fe0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
29ff0 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
2a000 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2a010 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2a020 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
2a030 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
2a040 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20  meter.  ^The.** 
2a050 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2a060 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2a070 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
2a080 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2a090 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
2a0a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2a0b0 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
2a0c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
2a0d0 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
2a0e0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
2a0f0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
2a100 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
2a110 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
2a120 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74  ..** ^A [protect
2a130 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2a140 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
2a150 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
2a160 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
2a170 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2a180 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
2a190 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
2a1a0 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
2a1b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2a1c0 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
2a1d0 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
2a1e0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
2a1f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2a200 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
2a210 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
2a220 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
2a230 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
2a240 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
2a250 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2a260 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
2a270 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
2a280 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
2a290 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
2a2a0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2a2b0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
2a2c0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
2a2d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2a2e0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2a2f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2a300 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2a310 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
2a320 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
2a330 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
2a340 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2a350 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a360 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
2a370 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2a380 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2a390 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
2a3a0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2a3b0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2a3c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2a3d0 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
2a3e0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2a3f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2a400 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
2a410 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
2a420 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a430 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
2a440 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2a450 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2a460 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
2a470 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2a480 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2a490 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
2a4a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2a4b0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2a4c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2a4d0 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
2a4e0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
2a4f0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2a500 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
2a510 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
2a520 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
2a530 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2a540 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2a550 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
2a560 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2a570 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2a580 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2a590 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2a5a0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2a5b0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2a5c0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
2a5d0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2a5e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a5f0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
2a600 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2a610 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
2a620 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2a630 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2a640 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
2a650 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
2a660 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73  _value*);.void s
2a670 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
2a680 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
2a690 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
2a6a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a6b0 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
2a6c0 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
2a6d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
2a6e0 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20  ctions are used 
2a6f0 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61  to add new colla
2a700 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74  tion sequences t
2a710 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  o the.** [databa
2a720 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
2a730 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
2a740 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
2a750 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
2a760 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61  of the new colla
2a770 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
2a780 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20   specified as a 
2a790 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2a7a0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
2a7b0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
2a7c0 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
2a7d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2a7e0 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
2a7f0 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69   string for sqli
2a800 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2a810 74 69 6f 6e 31 36 28 29 2e 20 5e 49 6e 20 61 6c  tion16(). ^In al
2a820 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e  l cases.** the n
2a830 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73  ame is passed as
2a840 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
2a850 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2a860 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2a870 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
2a880 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
2a890 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
2a8a0 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
2a8b0 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16LE], or [SQL
2a8c0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e  ITE_UTF16BE], in
2a8d0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68  dicating that th
2a8e0 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a  e user-supplied.
2a8f0 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63  ** routine expec
2a900 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20  ts to be passed 
2a910 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
2a920 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  ngs encoded usin
2a930 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d  g UTF-8,.** UTF-
2a940 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
2a950 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d  , or UTF-16 big-
2a960 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
2a970 76 65 6c 79 2e 20 5e 54 68 65 0a 2a 2a 20 74 68  vely. ^The.** th
2a980 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67  ird argument mig
2a990 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49  ht also be [SQLI
2a9a0 54 45 5f 55 54 46 31 36 5d 20 74 6f 20 69 6e 64  TE_UTF16] to ind
2a9b0 69 63 61 74 65 20 74 68 61 74 20 74 68 65 20 72  icate that the r
2a9c0 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74  outine.** expect
2a9d0 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 62 65  s pointers to be
2a9e0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
2a9f0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
2aa00 74 65 20 6f 72 64 65 72 2c 20 6f 72 20 74 68 65  te order, or the
2aa10 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63 61 6e  .** argument can
2aa20 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
2aa30 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20 74 68  6_ALIGNED] if th
2aa40 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65  e.** the routine
2aa50 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72   expects pointer
2aa60 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64  s to 16-bit word
2aa70 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73   aligned strings
2aa80 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e  .** of UTF-16 in
2aa90 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
2aaa0 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20   order..**.** A 
2aab0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75  pointer to the u
2aac0 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75  ser supplied rou
2aad0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73  tine must be pas
2aae0 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68  sed as the fifth
2aaf0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
2ab00 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
2ab10 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20  his is the same 
2ab20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  as deleting the 
2ab30 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
2ab40 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53  uence (so that S
2ab50 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c  QLite cannot cal
2ab60 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a  l it anymore)..*
2ab70 2a 20 5e 45 61 63 68 20 74 69 6d 65 20 74 68 65  * ^Each time the
2ab80 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70   application sup
2ab90 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  plied function i
2aba0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73  s invoked, it is
2abb0 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74   passed.** as it
2abc0 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
2abd0 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  r a copy of the 
2abe0 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20  void* passed as 
2abf0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
2ac00 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
2ac10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2ac20 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
2ac30 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2ac40 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  16()..**.** ^The
2ac50 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d   remaining argum
2ac60 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c  ents to the appl
2ac70 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
2ac80 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f   routine are two
2ac90 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63   strings,.** eac
2aca0 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  h represented by
2acb0 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61   a (length, data
2acc0 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64  ) pair and encod
2acd0 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69  ed in the encodi
2ace0 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70  ng.** that was p
2acf0 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
2ad00 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e  rd argument when
2ad10 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   the collation s
2ad20 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72  equence was.** r
2ad30 65 67 69 73 74 65 72 65 64 2e 20 20 54 68 65 20  egistered.  The 
2ad40 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2ad50 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f  ned collation ro
2ad60 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20  utine should.** 
2ad70 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c  return negative,
2ad80 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76   zero or positiv
2ad90 65 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  e if the first s
2ada0 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
2adb0 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c  an,.** equal to,
2adc0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
2add0 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69   the second stri
2ade0 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47  ng. i.e. (STRING
2adf0 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a  1 - STRING2)..**
2ae00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ae10 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2ae20 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
2ae30 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2ae40 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
2ae50 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74  except that it t
2ae60 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72  akes an extra ar
2ae70 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
2ae80 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  a destructor for
2ae90 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  .** the collatio
2aea0 6e 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  n.  ^The destruc
2aeb0 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68  tor is called wh
2aec0 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
2aed0 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64   is.** destroyed
2aee0 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61   and is passed a
2aef0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75   copy of the fou
2af00 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f  rth parameter vo
2af10 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f  id* pointer.** o
2af20 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  f the sqlite3_cr
2af30 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2af40 32 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  2()..** ^Collati
2af50 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65  ons are destroye
2af60 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
2af70 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
2af80 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  ter calls to the
2af90 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  .** collation cr
2afa0 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
2afb0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61   or when the [da
2afc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2afd0 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20  n] is closed.** 
2afe0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
2aff0 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  lose()]..**.** S
2b000 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74  ee also:  [sqlit
2b010 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2b020 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ded()] and [sqli
2b030 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2b040 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  eded16()]..*/.in
2b050 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2b060 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
2b070 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2b080 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
2b090 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
2b0a0 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
2b0b0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
2b0c0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
2b0d0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
2b0e0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2b0f0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2b100 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
2b110 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
2b120 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
2b130 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
2b140 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
2b150 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
2b160 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
2b170 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  st void*),.  voi
2b180 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
2b190 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
2b1a0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2b1b0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
2b1c0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  *, .  const void
2b1d0 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65   *zName,.  int e
2b1e0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
2b1f0 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
2b200 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2b210 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2b220 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
2b230 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2b240 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
2b250 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
2b260 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67  ^To avoid having
2b270 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
2b280 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2b290 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
2b2a0 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
2b2b0 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
2b2c0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2b2d0 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
2b2e0 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
2b2f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b300 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f  tion] to be invo
2b310 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  ked whenever an 
2b320 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
2b330 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
2b340 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
2b350 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  ** ^If the funct
2b360 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
2b370 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
2b380 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2b390 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
2b3a0 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
2b3b0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
2b3c0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
2b3d0 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
2b3e0 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
2b3f0 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20  d in UTF-8. ^If 
2b400 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2b410 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
2b420 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d  used,.** the nam
2b430 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73  es are passed as
2b440 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
2b450 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
2b460 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  rder..** ^A call
2b470 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
2b480 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65  ion replaces the
2b490 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74   existing collat
2b4a0 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62  ion-needed callb
2b4b0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65  ack..**.** ^(Whe
2b4c0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
2b4d0 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
2b4e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
2b4f0 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
2b500 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
2b510 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2b520 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2b530 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
2b540 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2b550 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
2b560 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2b570 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
2b580 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
2b590 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2b5a0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
2b5b0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
2b5c0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
2b5d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
2b5e0 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
2b5f0 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61   the most desira
2b600 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
2b610 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
2b620 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
2b630 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f  equired.  The fo
2b640 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2b650 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
2b660 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
2b670 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2b680 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  .)^.**.** The ca
2b690 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2b6a0 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
2b6b0 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
2b6c0 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
2b6d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2b6e0 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
2b6f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2b700 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
2b710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2b720 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2b730 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2b740 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2b750 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
2b760 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
2b770 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2b780 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
2b790 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
2b7a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2b7b0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
2b7c0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2b7d0 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
2b7e0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
2b7f0 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
2b800 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23  nst void*).);..#
2b810 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53  ifdef SQLITE_HAS
2b820 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65  _CODEC./*.** Spe
2b830 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
2b840 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
2b850 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
2b860 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
2b870 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
2b880 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
2b890 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
2b8a0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
2b8b0 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
2b8c0 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
2b8d0 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
2b8e0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
2b8f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  */.int sqlite3_k
2b900 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
2b910 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
2b920 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2b930 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
2b940 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2b950 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
2b960 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
2b970 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67  .);../*.** Chang
2b980 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20  e the key on an 
2b990 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20  open database.  
2b9a0 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  If the current d
2b9b0 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a  atabase is not.*
2b9c0 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69  * encrypted, thi
2b9d0 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65  s routine will e
2b9e0 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70  ncrypt it.  If p
2b9f0 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d  New==0 or nNew==
2ba00 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  0, the.** databa
2ba10 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e  se is decrypted.
2ba20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
2ba30 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
2ba40 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
2ba50 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
2ba60 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
2ba70 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
2ba80 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28  t sqlite3_rekey(
2ba90 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2baa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bab0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
2bac0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
2bad0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
2bae0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
2baf0 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
2bb00 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  /.);../*.** Spec
2bb10 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
2bb20 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45  on key for a SEE
2bb30 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
2bb40 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
2bb50 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45  , none of the SE
2bb60 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  E routines will 
2bb70 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  work..*/.void sq
2bb80 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73  lite3_activate_s
2bb90 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  ee(.  const char
2bba0 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
2bbb0 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
2bbc0 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
2bbd0 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53  #endif..#ifdef S
2bbe0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52  QLITE_ENABLE_CER
2bbf0 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  OD./*.** Specify
2bc00 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
2bc10 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20  key for a CEROD 
2bc20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
2bc30 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
2bc40 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52   none of the CER
2bc50 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  OD routines will
2bc60 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
2bc70 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
2bc80 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63  cerod(.  const c
2bc90 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
2bca0 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
2bcb0 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
2bcc0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
2bcd0 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65   CAPI3REF: Suspe
2bce0 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
2bcf0 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a   A Short Time.**
2bd00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bd10 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
2bd20 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
2bd30 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
2bd40 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
2bd50 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
2bd60 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
2bd70 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
2bd80 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
2bd90 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eter..**.** ^If 
2bda0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
2bdb0 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75  stem does not su
2bdc0 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75  pport sleep requ
2bdd0 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c  ests with.** mil
2bde0 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65  lisecond time re
2bdf0 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74  solution, then t
2be00 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20  he time will be 
2be10 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a  rounded up to.**
2be20 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63   the nearest sec
2be30 6f 6e 64 2e 20 5e 54 68 65 20 6e 75 6d 62 65 72  ond. ^The number
2be40 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
2be50 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
2be60 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
2be70 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
2be80 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
2be90 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  urned..**.** ^SQ
2bea0 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
2beb0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
2bec0 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
2bed0 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
2bee0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
2bef0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
2bf00 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ject..*/.int sql
2bf10 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
2bf20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bf30 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
2bf40 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
2bf50 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
2bf60 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
2bf70 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
2bf80 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
2bf90 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
2bfa0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
2bfb0 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
2bfc0 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
2bfd0 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
2bfe0 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
2bff0 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65  ed by SQLite whe
2c000 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
2c010 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  in [sqlite3_vfs 
2c020 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62  | VFS].** will b
2c030 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
2c040 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e   directory.)^  ^
2c050 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
2c060 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
2c070 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
2c080 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
2c090 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
2c0a0 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
2c0b0 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
2c0c0 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
2c0d0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
2c0e0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
2c0f0 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
2c100 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
2c110 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
2c120 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
2c130 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
2c140 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
2c150 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
2c160 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
2c170 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
2c180 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
2c190 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
2c1a0 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
2c1b0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
2c1c0 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
2c1d0 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
2c1e0 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
2c1f0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
2c200 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
2c210 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
2c220 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
2c230 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
2c240 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
2c250 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
2c260 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
2c270 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70  **.** ^The [temp
2c280 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2c290 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
2c2a0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
2c2b0 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
2c2c0 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
2c2d0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2c2e0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2c2f0 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
2c300 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70  re,.** the [temp
2c310 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2c320 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
2c330 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
2c340 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
2c350 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
2c360 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
2c370 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
2c380 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
2c390 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
2c3a0 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
2c3b0 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
2c3c0 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
2c3d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
2c3e0 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
2c3f0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
2c400 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
2c410 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
2c420 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
2c430 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
2c440 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
2c450 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2c460 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2c470 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
2c480 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70  use of the [temp
2c490 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2c4a0 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
2c4b0 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53  be avoided..*/.S
2c4c0 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61  QLITE_EXTERN cha
2c4d0 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  r *sqlite3_temp_
2c4e0 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a  directory;../*.*
2c4f0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
2c500 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74   For Auto-Commit
2c510 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44   Mode.** KEYWORD
2c520 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
2c530 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ode}.**.** ^The 
2c540 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
2c550 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61  commit() interfa
2c560 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
2c570 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
2c580 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
2c590 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2c5a0 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
2c5b0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
2c5c0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2c5d0 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .  ^Autocommit m
2c5e0 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66  ode is on by def
2c5f0 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ault..** ^Autoco
2c600 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
2c610 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49  abled by a [BEGI
2c620 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
2c630 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
2c640 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
2c650 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
2c660 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
2c670 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
2c680 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
2c690 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
2c6a0 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
2c6b0 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
2c6c0 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
2c6d0 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
2c6e0 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
2c6f0 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b  ITE_IOERR],.** [
2c700 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
2c710 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
2c720 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
2c730 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
2c740 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
2c750 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
2c760 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
2c770 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
2c780 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77  to.** find out w
2c790 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75  hether SQLite au
2c7a0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
2c7b0 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
2c7c0 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
2c7d0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
2c7e0 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
2c7f0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  n..**.** If anot
2c800 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
2c810 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
2c820 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
2c830 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2c840 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
2c850 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
2c860 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
2c870 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
2c880 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
2c890 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
2c8a0 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
2c8b0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
2c8c0 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
2c8d0 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
2c8e0 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
2c8f0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
2c900 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
2c910 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
2c920 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
2c930 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2c940 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
2c950 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
2c960 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
2c970 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62  gs.  ^The [datab
2c980 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
2c990 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2c9a0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
2c9b0 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
2c9c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2c9d0 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74  n].** that was t
2c9e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2c9f0 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
2ca00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2ca10 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
2ca20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
2ca30 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
2ca40 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
2ca50 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
2ca60 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  place..*/.sqlite
2ca70 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
2ca80 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
2ca90 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2caa0 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
2cab0 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
2cac0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
2cad0 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
2cae0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2caf0 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
2cb00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cb10 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
2cb20 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
2cb30 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2cb40 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
2cb50 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
2cb60 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
2cb70 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2cb80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2cb90 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
2cba0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
2cbb0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2cbc0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2cbd0 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
2cbe0 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
2cbf0 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
2cc00 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
2cc10 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
2cc20 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
2cc30 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
2cc40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2cc50 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
2cc60 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
2cc70 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2cc80 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
2cc90 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
2cca0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2ccb0 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
2ccc0 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
2ccd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2cce0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
2ccf0 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
2cd00 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
2cd10 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
2cd20 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2cd30 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
2cd40 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
2cd50 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
2cd60 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
2cd70 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2cd80 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
2cd90 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
2cda0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
2cdb0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
2cdc0 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
2cdd0 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20  tion is [COMMIT 
2cde0 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a  | committed]..**
2cdf0 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
2ce00 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
2ce10 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2ce20 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
2ce30 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2ce40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ce50 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2ce60 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2ce70 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2ce80 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2ce90 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2cea0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
2ceb0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2cec0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
2ced0 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c  n is [ROLLBACK |
2cee0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a   rolled back]..*
2cef0 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
2cf00 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2cf10 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
2cf20 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2cf30 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
2cf40 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2cf50 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
2cf60 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72  den..** ^The pAr
2cf70 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
2cf80 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
2cf90 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2cfa0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
2cfb0 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
2cfc0 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ok function retu
2cfd0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a  rns non-zero,.**
2cfe0 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
2cff0 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
2d000 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
2d010 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d020 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
2d030 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33  C,P) and sqlite3
2d040 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
2d050 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a  ,C,P) functions.
2d060 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20  ** return the P 
2d070 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
2d080 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
2d090 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2d0a0 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  tion.** on the s
2d0b0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
2d0c0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
2d0d0 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
2d0e0 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65  first call for e
2d0f0 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20  ach function on 
2d100 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  D..**.** The cal
2d110 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61  lback implementa
2d120 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f  tion must not do
2d130 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
2d140 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
2d150 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d160 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
2d170 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  ed the callback.
2d180 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a    Any actions.**
2d190 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64   to modify the d
2d1a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d1b0 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72  on must be defer
2d1c0 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20  red until after 
2d1d0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f  the.** completio
2d1e0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
2d1f0 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74  3_step()] call t
2d200 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
2d210 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72  e commit.** or r
2d220 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20  ollback hook in 
2d230 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
2d240 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
2d250 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d260 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2d270 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
2d280 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
2d290 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d2a0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
2d2b0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
2d2c0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
2d2d0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74  h..**.** ^Regist
2d2e0 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
2d2f0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
2d300 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
2d310 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d  ** ^When the com
2d320 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  mit hook callbac
2d330 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  k routine return
2d340 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d  s zero, the [COM
2d350 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  MIT].** operatio
2d360 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20  n is allowed to 
2d370 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c  continue normall
2d380 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d  y.  ^If the comm
2d390 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72  it hook.** retur
2d3a0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
2d3b0 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69  n the [COMMIT] i
2d3c0 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
2d3d0 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a   a [ROLLBACK]..*
2d3e0 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  * ^The rollback 
2d3f0 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  hook is invoked 
2d400 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68  on a rollback th
2d410 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  at results from 
2d420 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b  a commit.** hook
2d430 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a   returning non-z
2d440 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20  ero, just as it 
2d450 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e  would be with an
2d460 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b  y other rollback
2d470 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ..**.** ^For the
2d480 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
2d490 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
2d4a0 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
2d4b0 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c  have been.** rol
2d4c0 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65  led back if an e
2d4d0 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43  xplicit "ROLLBAC
2d4e0 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  K" statement is 
2d4f0 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20  executed, or.** 
2d500 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73  an error or cons
2d510 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e  traint causes an
2d520 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61   implicit rollba
2d530 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20  ck to occur..** 
2d540 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61  ^The rollback ca
2d550 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
2d560 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
2d570 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74  action is.** aut
2d580 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
2d590 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74  d back because t
2d5a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2d5b0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
2d5c0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2d5d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70   the [sqlite3_up
2d5e0 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74  date_hook()] int
2d5f0 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20  erface..*/.void 
2d600 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
2d610 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
2d620 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
2d630 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
2d640 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2d650 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
2d660 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
2d670 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
2d680 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
2d690 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
2d6a0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
2d6b0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
2d6c0 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  te_hook() interf
2d6d0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2d6e0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2d6f0 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  n.** with the [d
2d700 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d710 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62  on] identified b
2d720 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
2d730 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  ment.** to be in
2d740 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2d750 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
2d760 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
2d770 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  eted..** ^Any ca
2d780 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
2d790 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2d7a0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2d7b0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2d7c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d7d0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2d7e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
2d7f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2d800 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2d810 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76   function to inv
2d820 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f  oke when a.** ro
2d830 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
2d840 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
2d850 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  d..** ^The first
2d860 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2d870 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
2d880 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
2d890 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
2d8a0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2d8b0 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73  ook()..** ^The s
2d8c0 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61  econd callback a
2d8d0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
2d8e0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  f [SQLITE_INSERT
2d8f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  ], [SQLITE_DELET
2d900 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
2d910 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e  E_UPDATE], depen
2d920 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72  ding on the oper
2d930 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
2d940 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  d the callback.*
2d950 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  * to be invoked.
2d960 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2d970 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
2d980 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
2d990 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
2d9a0 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  ters to the.** d
2d9b0 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c  atabase and tabl
2d9c0 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e  e name containin
2d9d0 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72  g the affected r
2d9e0 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61  ow..** ^The fina
2d9f0 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
2da00 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77  eter is the [row
2da10 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a  id] of the row..
2da20 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20  ** ^In the case 
2da30 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68  of an update, th
2da40 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  is is the [rowid
2da50 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61  ] after the upda
2da60 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a  te takes place..
2da70 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61  **.** ^(The upda
2da80 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69  te hook is not i
2da90 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65  nvoked when inte
2daa0 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c  rnal system tabl
2dab0 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69  es are.** modifi
2dac0 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f  ed (i.e. sqlite_
2dad0 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74  master and sqlit
2dae0 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a  e_sequence).)^.*
2daf0 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72  *.** ^In the cur
2db00 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
2db10 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20  ion, the update 
2db20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69  hook.** is not i
2db30 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c  nvoked when dupl
2db40 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65  ication rows are
2db50 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65   deleted because
2db60 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f   of an.** [ON CO
2db70 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46  NFLICT | ON CONF
2db80 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c  LICT REPLACE] cl
2db90 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74  ause.  ^Nor is t
2dba0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
2dbb0 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72  * invoked when r
2dbc0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
2dbd0 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63  using the [trunc
2dbe0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
2dbf0 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74  ]..** The except
2dc00 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20  ions defined in 
2dc10 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d  this paragraph m
2dc20 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61  ight change in a
2dc30 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
2dc40 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
2dc50 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
2dc60 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ook implementati
2dc70 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
2dc80 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
2dc90 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
2dca0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2dcb0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
2dcc0 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
2dcd0 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
2dce0 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
2dcf0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2dd00 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
2dd10 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
2dd20 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
2dd30 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
2dd40 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
2dd50 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
2dd60 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a  he update hook..
2dd70 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
2dd80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2dd90 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2dda0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
2ddb0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
2ddc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ddd0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
2dde0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
2ddf0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
2de00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2de10 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2de20 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e  (D,C,P) function
2de30 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
2de40 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20  P argument from 
2de50 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
2de60 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  l.** on the same
2de70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2de80 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
2de90 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
2dea0 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a  st call on D..**
2deb0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
2dec0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
2ded0 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71  _hook()] and [sq
2dee0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2def0 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ook()].** interf
2df00 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  aces..*/.void *s
2df10 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2df20 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ok(.  sqlite3*, 
2df30 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  .  void(*)(void 
2df40 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73  *,int ,char cons
2df50 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  t *,char const *
2df60 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c  ,sqlite3_int64),
2df70 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a  .  void*.);../*.
2df80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
2df90 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53  ble Or Disable S
2dfa0 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68  hared Pager Cach
2dfb0 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  e.** KEYWORDS: {
2dfc0 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a  shared cache}.**
2dfd0 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
2dfe0 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
2dff0 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69  sables the shari
2e000 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
2e010 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20  se cache.** and 
2e020 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75  schema data stru
2e030 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b  ctures between [
2e040 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e050 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e  ion | connection
2e060 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  s].** to the sam
2e070 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72  e database. Shar
2e080 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ing is enabled i
2e090 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
2e0a0 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69  s true.** and di
2e0b0 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  sabled if the ar
2e0c0 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e  gument is false.
2e0d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20  )^.**.** ^Cache 
2e0e0 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  sharing is enabl
2e0f0 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ed and disabled 
2e100 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72  for an entire pr
2e110 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69  ocess..** This i
2e120 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66  s a change as of
2e130 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2e140 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20  3.5.0. In prior 
2e150 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2e160 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77  te,.** sharing w
2e170 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  as enabled or di
2e180 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20  sabled for each 
2e190 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c  thread separatel
2e1a0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63  y..**.** ^(The c
2e1b0 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64  ache sharing mod
2e1c0 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e  e set by this in
2e1d0 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20  terface effects 
2e1e0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
2e1f0 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * calls to [sqli
2e200 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2e210 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2e220 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  , and [sqlite3_o
2e230 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69  pen16()]..** Exi
2e240 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63  sting database c
2e250 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69  onnections conti
2e260 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72  nue use the shar
2e270 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74  ing mode.** that
2e280 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61   was in effect a
2e290 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20  t the time they 
2e2a0 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a  were opened.)^.*
2e2b0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
2e2c0 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
2e2d0 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
2e2e0 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62  d cache was enab
2e2f0 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
2e300 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2e310 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65    An [error code
2e320 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74  ] is returned ot
2e330 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a  herwise.)^.**.**
2e340 20 5e 53 68 61 72 65 64 20 63 61 63 68 65 20 69   ^Shared cache i
2e350 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
2e360 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20  fault. But this 
2e370 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a  might change in.
2e380 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ** future releas
2e390 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  es of SQLite.  A
2e3a0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
2e3b0 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72   care about shar
2e3c0 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74  ed.** cache sett
2e3d0 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69  ing should set i
2e3e0 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a  t explicitly..**
2e3f0 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b  .** See Also:  [
2e400 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61  SQLite Shared-Ca
2e410 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74  che Mode].*/.int
2e420 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
2e430 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74  shared_cache(int
2e440 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e450 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46  EF: Attempt To F
2e460 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a  ree Heap Memory.
2e470 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e480 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2e490 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  y() interface at
2e4a0 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e  tempts to free N
2e4b0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61   bytes.** of hea
2e4c0 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c  p memory by deal
2e4d0 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73  locating non-ess
2e4e0 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ential memory al
2e4f0 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c  locations.** hel
2e500 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
2e510 65 20 6c 69 62 72 61 72 79 2e 20 20 20 4d 65 6d  e library.   Mem
2e520 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68  ory used to cach
2e530 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61  e database.** pa
2e540 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70  ges to improve p
2e550 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e  erformance is an
2e560 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d   example of non-
2e570 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
2e580 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
2e590 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72  lease_memory() r
2e5a0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2e5b0 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61  r of bytes actua
2e5c0 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68  lly freed,.** wh
2e5d0 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72  ich might be mor
2e5e0 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74  e or less than t
2e5f0 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73  he amount reques
2e600 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ted..*/.int sqli
2e610 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2e620 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ry(int);../*.** 
2e630 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65  CAPI3REF: Impose
2e640 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
2e650 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65   Size.**.** ^The
2e660 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
2e670 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72  ap_limit() inter
2e680 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22 73  face places a "s
2e690 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e  oft" limit.** on
2e6a0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
2e6b0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
2e6c0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
2e6d0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e   by SQLite..** ^
2e6e0 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61  If an internal a
2e6f0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71  llocation is req
2e700 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c  uested that woul
2e710 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  d exceed the.** 
2e720 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
2e730 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2e740 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69  e_memory()] is i
2e750 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a  nvoked one or.**
2e760 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66   more times to f
2e770 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63  ree up some spac
2e780 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c  e before the all
2e790 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f  ocation is perfo
2e7a0 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rmed..**.** ^The
2e7b0 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64   limit is called
2e7c0 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20   "soft" because 
2e7d0 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  if [sqlite3_rele
2e7e0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a  ase_memory()].**
2e7f0 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66   cannot free suf
2e800 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74  ficient memory t
2e810 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69  o prevent the li
2e820 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65  mit from being e
2e830 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20  xceeded,.** the 
2e840 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
2e850 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74  ted anyway and t
2e860 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  he current opera
2e870 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a  tion proceeds..*
2e880 2a 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  *.** ^A negative
2e890 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66   or zero value f
2e8a0 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20  or N means that 
2e8b0 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74  there is no soft
2e8c0 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a   heap limit and.
2e8d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** [sqlite3_rele
2e8e0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69  ase_memory()] wi
2e8f0 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ll only be calle
2e900 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73  d when memory is
2e910 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e   exhausted..** ^
2e920 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
2e930 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  e for the soft h
2e940 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72  eap limit is zer
2e950 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  o..**.** ^(SQLit
2e960 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65  e makes a best e
2e970 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74  ffort to honor t
2e980 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
2e990 69 74 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68  it..** But if th
2e9a0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2e9b0 74 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f  t cannot be hono
2e9c0 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77  red, execution w
2e9d0 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20  ill.** continue 
2e9e0 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72  without error or
2e9f0 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 29 5e   notification.)^
2ea00 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68    This is why th
2ea10 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61  e limit is.** ca
2ea20 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69  lled a "soft" li
2ea30 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 76 69  mit.  It is advi
2ea40 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  sory only..**.**
2ea50 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
2ea60 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
2ea70 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  this routine onl
2ea80 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68  y constrained th
2ea90 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
2eaa0 63 61 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c  cated by a singl
2eab0 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 20 73  e thread - the s
2eac0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2ead0 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ich this routine
2eae0 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e  .** runs.  Begin
2eaf0 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65  ning with SQLite
2eb00 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
2eb10 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
2eb20 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65  mit is.** applie
2eb30 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73  d to all threads
2eb40 2e 20 54 68 65 20 76 61 6c 75 65 20 73 70 65 63  . The value spec
2eb50 69 66 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f  ified for the so
2eb60 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a  ft heap limit.**
2eb70 20 69 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75   is an upper bou
2eb80 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20  nd on the total 
2eb90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2eba0 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64  n for all thread
2ebb0 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e  s. In.** version
2ebc0 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20   3.5.0 there is 
2ebd0 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72  no mechanism for
2ebe0 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65   limiting the he
2ebf0 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20  ap usage for.** 
2ec00 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61  individual threa
2ec10 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ds..*/.void sqli
2ec20 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
2ec30 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mit(int);../*.**
2ec40 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 72 61   CAPI3REF: Extra
2ec50 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75  ct Metadata Abou
2ec60 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20  t A Column Of A 
2ec70 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  Table.**.** ^Thi
2ec80 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
2ec90 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74  s metadata about
2eca0 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75   a specific colu
2ecb0 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63  mn of a specific
2ecc0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61 62  .** database tab
2ecd0 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73  le accessible us
2ece0 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61 73  ing the [databas
2ecf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
2ed00 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61  ndle.** passed a
2ed10 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63  s the first func
2ed20 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2ed30 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e  *.** ^The column
2ed40 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62   is identified b
2ed50 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68  y the second, th
2ed60 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
2ed70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20  arameters to.** 
2ed80 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  this function. ^
2ed90 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2eda0 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74  eter is either t
2edb0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
2edc0 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e  atabase.** (i.e.
2edd0 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c   "main", "temp",
2ede0 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20   or an attached 
2edf0 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69  database) contai
2ee00 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69  ning the specifi
2ee10 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e  ed.** table or N
2ee20 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e  ULL. ^If it is N
2ee30 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74  ULL, then all at
2ee40 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
2ee50 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a   are searched.**
2ee60 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75   for the table u
2ee70 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
2ee80 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79 20  gorithm used by 
2ee90 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
2eea0 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76  ine to.** resolv
2eeb0 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61  e unqualified ta
2eec0 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a  ble references..
2eed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
2eee0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
2eef0 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66  meters to this f
2ef00 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20  unction are the 
2ef10 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
2ef20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
2ef30 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20  desired column, 
2ef40 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65  respectively. Ne
2ef50 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70  ither of these p
2ef60 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79  arameters.** may
2ef70 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2ef80 5e 4d 65 74 61 64 61 74 61 20 69 73 20 72 65 74  ^Metadata is ret
2ef90 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67  urned by writing
2efa0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c   to the memory l
2efb0 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20  ocations passed 
2efc0 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e  as the 5th.** an
2efd0 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72  d subsequent par
2efe0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
2eff0 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f  function. ^Any o
2f000 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74  f these argument
2f010 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c  s may be.** NULL
2f020 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
2f030 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2f040 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74  g element of met
2f050 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64  adata is omitted
2f060 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b  ..**.** ^(<block
2f070 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2f080 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2f090 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74  <tr><th> Paramet
2f0a0 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62  er <th> Output<b
2f0b0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73  r>Type <th>  Des
2f0c0 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  cription.**.** <
2f0d0 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e  tr><td> 5th <td>
2f0e0 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
2f0f0 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c  > Data type.** <
2f100 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e  tr><td> 6th <td>
2f110 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
2f120 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c  > Name of defaul
2f130 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  t collation sequ
2f140 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ence.** <tr><td>
2f150 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   7th <td> int   
2f160 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
2f170 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20  if column has a 
2f180 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
2f190 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  int.** <tr><td> 
2f1a0 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  8th <td> int    
2f1b0 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2f1c0 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74  f column is part
2f1d0 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20   of the PRIMARY 
2f1e0 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  KEY.** <tr><td> 
2f1f0 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  9th <td> int    
2f200 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2f210 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54  f column is [AUT
2f220 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c  OINCREMENT].** <
2f230 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
2f240 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
2f250 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   ^The memory poi
2f260 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63  nted to by the c
2f270 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72  haracter pointer
2f280 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74  s returned for t
2f290 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f  he.** declaratio
2f2a0 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61  n type and colla
2f2b0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
2f2c0 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69   valid only unti
2f2d0 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61  l the next.** ca
2f2e0 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65  ll to any SQLite
2f2f0 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   API function..*
2f300 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  *.** ^If the spe
2f310 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20  cified table is 
2f320 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c  actually a view,
2f330 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
2f340 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2f350 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
2f360 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20  ified column is 
2f370 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f  "rowid", "oid" o
2f380 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20  r "_rowid_" and 
2f390 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50  an.** [INTEGER P
2f3a0 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75  RIMARY KEY] colu
2f3b0 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c  mn has been expl
2f3c0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c  icitly declared,
2f3d0 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
2f3e0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
2f3f0 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65  re set for the e
2f400 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
2f410 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20  ed column. ^(If 
2f420 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65  there is no.** e
2f430 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
2f440 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  ed [INTEGER PRIM
2f450 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c  ARY KEY] column,
2f460 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
2f470 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
2f480 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77  re set as follow
2f490 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  s:.**.** <pre>.*
2f4a0 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a  *     data type:
2f4b0 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20   "INTEGER".**   
2f4c0 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75    collation sequ
2f4d0 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a  ence: "BINARY".*
2f4e0 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20  *     not null: 
2f4f0 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79  0.**     primary
2f500 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61   key: 1.**     a
2f510 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30  uto increment: 0
2f520 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a  .** </pre>)^.**.
2f530 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69  ** ^(This functi
2f540 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20  on may load one 
2f550 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20  or more schemas 
2f560 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69  from database fi
2f570 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72  les. If an.** er
2f580 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
2f590 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20  g this process, 
2f5a0 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73  or if the reques
2f5b0 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c  ted table or col
2f5c0 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65  umn.** cannot be
2f5d0 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f   found, an [erro
2f5e0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2f5f0 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72  ned and an error
2f600 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a   message left.**
2f610 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   in the [databas
2f620 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
2f630 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75  o be retrieved u
2f640 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72  sing sqlite3_err
2f650 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  msg()).)^.**.** 
2f660 5e 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c  ^This API is onl
2f670 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2f680 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2f690 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2f6a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2f6b0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2f6c0 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2f6d0 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  or symbol define
2f6e0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2f6f0 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d  3_table_column_m
2f700 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74  etadata(.  sqlit
2f710 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2f720 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63         /* Connec
2f730 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  tion handle */. 
2f740 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
2f750 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20  Name,        /* 
2f760 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72  Database name or
2f770 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74   NULL */.  const
2f780 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d   char *zTableNam
2f790 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  e,     /* Table 
2f7a0 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  name */.  const 
2f7b0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d  char *zColumnNam
2f7c0 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20  e,    /* Column 
2f7d0 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  name */.  char c
2f7e0 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70  onst **pzDataTyp
2f7f0 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  e,    /* OUTPUT:
2f800 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74   Declared data t
2f810 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ype */.  char co
2f820 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c  nst **pzCollSeq,
2f830 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2f840 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  Collation sequen
2f850 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74  ce name */.  int
2f860 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20   *pNotNull,     
2f870 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2f880 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20  UT: True if NOT 
2f890 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20  NULL constraint 
2f8a0 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20  exists */.  int 
2f8b0 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20  *pPrimaryKey,   
2f8c0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
2f8d0 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
2f8e0 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a  n part of PK */.
2f8f0 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20    int *pAutoinc 
2f900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2f910 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
2f920 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d   column is auto-
2f930 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a  increment */.);.
2f940 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f950 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
2f960 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  on.**.** ^This i
2f970 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61  nterface loads a
2f980 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  n SQLite extensi
2f990 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20  on library from 
2f9a0 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a  the named file..
2f9b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2f9c0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
2f9d0 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  n() interface at
2f9e0 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61  tempts to load a
2f9f0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78 74 65  n.** SQLite exte
2fa00 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f  nsion library co
2fa10 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66  ntained in the f
2fa20 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a  ile zFile..**.**
2fa30 20 5e 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e   ^The entry poin
2fa40 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e  t is zProc..** ^
2fa50 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20  zProc may be 0, 
2fa60 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
2fa70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e  e name of the en
2fa80 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66  try point.** def
2fa90 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65  aults to "sqlite
2faa0 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74  3_extension_init
2fab0 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  "..** ^The sqlit
2fac0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
2fad0 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  n() interface re
2fae0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
2faf0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
2fb00 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  and [SQLITE_ERRO
2fb10 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20  R] if something 
2fb20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
2fb30 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
2fb40 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20  rs and pzErrMsg 
2fb50 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74  is not 0, then t
2fb60 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  he.** [sqlite3_l
2fb70 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
2fb80 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
2fb90 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66   attempt to.** f
2fba0 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69  ill *pzErrMsg wi
2fbb0 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  th error message
2fbc0 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20   text stored in 
2fbd0 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e  memory.** obtain
2fbe0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2fbf0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20  _malloc()]. The 
2fc00 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
2fc10 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65 65 20  .** should free 
2fc20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63  this memory by c
2fc30 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2fc40 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
2fc50 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
2fc60 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65  g must be enable
2fc70 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2fc80 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
2fc90 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69  extension()] pri
2fca0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68  or to calling th
2fcb0 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72  is API,.** other
2fcc0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69  wise an error wi
2fcd0 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a  ll be returned..
2fce0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
2fcf0 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  he [load_extensi
2fd00 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  on() SQL functio
2fd10 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  n]..*/.int sqlit
2fd20 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
2fd30 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
2fd40 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f  ,          /* Lo
2fd50 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  ad the extension
2fd60 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62   into this datab
2fd70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a  ase connection *
2fd80 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2fd90 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d  zFile,    /* Nam
2fda0 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 20  e of the shared 
2fdb0 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69  library containi
2fdc0 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a  ng extension */.
2fdd0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
2fde0 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79  roc,    /* Entry
2fdf0 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64   point.  Derived
2fe00 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30   from zFile if 0
2fe10 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
2fe20 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50  rrMsg       /* P
2fe30 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ut error message
2fe40 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a   here if not 0 *
2fe50 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
2fe60 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
2fe70 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f  Disable Extensio
2fe80 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20  n Loading.**.** 
2fe90 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70  ^So as not to op
2fea0 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65  en security hole
2feb0 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69  s in older appli
2fec0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  cations that are
2fed0 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74  .** unprepared t
2fee0 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 74 65  o deal with exte
2fef0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61  nsion loading, a
2ff00 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66  nd as a means of
2ff10 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78   disabling.** ex
2ff20 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
2ff30 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
2ff40 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
2ff50 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  L, the following
2ff60 20 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69   API.** is provi
2ff70 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20  ded to turn the 
2ff80 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
2ff90 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61  tension()] mecha
2ffa0 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e  nism on and off.
2ffb0 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f  .**.** ^Extensio
2ffc0 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66  n loading is off
2ffd0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65   by default. See
2ffe0 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a   ticket #1863..*
2fff0 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c 69  * ^Call the sqli
30000 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
30010 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74  extension() rout
30020 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d  ine with onoff==
30030 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78 74  1.** to turn ext
30040 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f  ension loading o
30050 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69  n and call it wi
30060 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74  th onoff==0 to t
30070 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f  urn.** it back o
30080 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74  ff again..*/.int
30090 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
300a0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73  load_extension(s
300b0 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20  qlite3 *db, int 
300c0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
300d0 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74  API3REF: Automat
300e0 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45  ically Load An E
300f0 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  xtensions.**.** 
30100 5e 54 68 69 73 20 41 50 49 20 63 61 6e 20 62 65  ^This API can be
30110 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67   invoked at prog
30120 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f  ram startup in o
30130 72 64 65 72 20 74 6f 20 72 65 67 69 73 74 65 72  rder to register
30140 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
30150 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65  statically linke
30160 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61  d extensions tha
30170 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61  t will be availa
30180 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65  ble.** to all ne
30190 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
301a0 65 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20  ections]..**.** 
301b0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  ^(This routine s
301c0 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20  tores a pointer 
301d0 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  to the extension
301e0 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20   entry point.** 
301f0 69 6e 20 61 6e 20 61 72 72 61 79 20 74 68 61 74  in an array that
30200 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
30210 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
30220 63 28 29 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f  c()].  That memo
30230 72 79 0a 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63  ry.** is dealloc
30240 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
30250 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
30260 6e 73 69 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  nsion()].)^.**.*
30270 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
30280 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 65 78   registers an ex
30290 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f  tension entry po
302a0 69 6e 74 20 74 68 61 74 20 69 73 0a 2a 2a 20 61  int that is.** a
302b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
302c0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
302d0 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f  new [database co
302e0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20  nnection].** is 
302f0 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71  opened using [sq
30300 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
30310 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
30320 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
30330 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a  3_open_v2()]..**
30340 20 5e 44 75 70 6c 69 63 61 74 65 20 65 78 74 65   ^Duplicate exte
30350 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63  nsions are detec
30360 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74  ted so calling t
30370 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d  his routine.** m
30380 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69  ultiple times wi
30390 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65  th the same exte
303a0 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73  nsion is harmles
303b0 73 2e 0a 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63  s..** ^Automatic
303c0 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c   extensions appl
303d0 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72  y across all thr
303e0 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  eads..*/.int sql
303f0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
30400 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72  ion(void (*xEntr
30410 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a  yPoint)(void));.
30420 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30430 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63   Reset Automatic
30440 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
30450 6e 67 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ng.**.** ^(This 
30460 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
30470 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79  s all previously
30480 20 72 65 67 69 73 74 65 72 65 64 20 61 75 74 6f   registered auto
30490 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69  matic.** extensi
304a0 6f 6e 73 2e 20 49 74 20 75 6e 64 6f 65 73 20 74  ons. It undoes t
304b0 68 65 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c  he effect of all
304c0 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74   prior.** [sqlit
304d0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
304e0 6e 28 29 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a  n()] calls.)^.**
304f0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
30500 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f  on disables auto
30510 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
30520 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e   in all threads.
30530 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
30540 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
30550 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a  nsion(void);../*
30560 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
30570 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
30580 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
30590 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
305a0 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62  nsidered.** to b
305b0 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20  e experimental. 
305c0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d   The interface m
305d0 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69  ight change in i
305e0 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73  ncompatible ways
305f0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20  ..** If this is 
30600 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f  a problem for yo
30610 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68  u, do not use th
30620 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74  e interface at t
30630 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  his time..**.** 
30640 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c  When the virtual
30650 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
30660 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20   stabilizes, we 
30670 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65  will declare the
30680 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69  .** interface fi
30690 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20  xed, support it 
306a0 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e  indefinitely, an
306b0 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f  d remove this co
306c0 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  mment..*/../*.**
306d0 20 53 74 72 75 63 74 75 72 65 73 20 75 73 65 64   Structures used
306e0 20 62 79 20 74 68 65 20 76 69 72 74 75 61 6c 20   by the virtual 
306f0 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a  table interface.
30700 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
30710 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73  t sqlite3_vtab s
30720 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70  qlite3_vtab;.typ
30730 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
30740 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73  te3_index_info s
30750 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
30760 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  o;.typedef struc
30770 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  t sqlite3_vtab_c
30780 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74  ursor sqlite3_vt
30790 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64  ab_cursor;.typed
307a0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
307b0 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33  3_module sqlite3
307c0 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20  _module;../*.** 
307d0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
307e0 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a  l Table Object.*
307f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
30800 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74  te3_module {virt
30810 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
30820 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72  }.**.** This str
30830 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65  ucture, sometime
30840 73 20 63 61 6c 6c 65 64 20 61 20 61 20 22 76 69  s called a a "vi
30850 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
30860 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73  le", .** defines
30870 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
30880 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 61  ion of a [virtua
30890 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20  l tables].  .** 
308a0 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  This structure c
308b0 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f  onsists mostly o
308c0 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  f methods for th
308d0 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20  e module..**.** 
308e0 5e 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ^A virtual table
308f0 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61 74   module is creat
30900 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e  ed by filling in
30910 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a   a persistent.**
30920 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
30930 73 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20  s structure and 
30940 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 65  passing a pointe
30950 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61 6e  r to that instan
30960 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ce.** to [sqlite
30970 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
30980 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )] or [sqlite3_c
30990 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
309a0 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69  )]..** ^The regi
309b0 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73  stration remains
309c0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20   valid until it 
309d0 69 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  is replaced by a
309e0 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f   different.** mo
309f0 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68  dule or until th
30a00 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
30a10 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20  ection] closes. 
30a20 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   The content.** 
30a30 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
30a40 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67  e must not chang
30a50 65 20 77 68 69 6c 65 20 69 74 20 69 73 20 72 65  e while it is re
30a60 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a  gistered with.**
30a70 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
30a80 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72  nnection..*/.str
30a90 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  uct sqlite3_modu
30aa0 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  le {.  int iVers
30ab0 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72  ion;.  int (*xCr
30ac0 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20  eate)(sqlite3*, 
30ad0 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20  void *pAux,.    
30ae0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
30af0 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  rgc, const char 
30b00 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20  *const*argv,.   
30b10 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
30b20 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61  te3_vtab **ppVTa
30b30 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  b, char**);.  in
30b40 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71  t (*xConnect)(sq
30b50 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41  lite3*, void *pA
30b60 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ux,.            
30b70 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e     int argc, con
30b80 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61  st char *const*a
30b90 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20  rgv,.           
30ba0 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62      sqlite3_vtab
30bb0 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a   **ppVTab, char*
30bc0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73  *);.  int (*xBes
30bd0 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f  tIndex)(sqlite3_
30be0 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
30bf0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a  ite3_index_info*
30c00 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63  );.  int (*xDisc
30c10 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f  onnect)(sqlite3_
30c20 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
30c30 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28  int (*xDestroy)(
30c40 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
30c50 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f  Tab);.  int (*xO
30c60 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  pen)(sqlite3_vta
30c70 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
30c80 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a  3_vtab_cursor **
30c90 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74  ppCursor);.  int
30ca0 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
30cb0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
30cc0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65  ;.  int (*xFilte
30cd0 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  r)(sqlite3_vtab_
30ce0 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78  cursor*, int idx
30cf0 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Num, const char 
30d00 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20  *idxStr,.       
30d10 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
30d20 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  c, sqlite3_value
30d30 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20   **argv);.  int 
30d40 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33  (*xNext)(sqlite3
30d50 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
30d60 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71    int (*xEof)(sq
30d70 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
30d80 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  r*);.  int (*xCo
30d90 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  lumn)(sqlite3_vt
30da0 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69  ab_cursor*, sqli
30db0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
30dc0 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77  t);.  int (*xRow
30dd0 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  id)(sqlite3_vtab
30de0 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
30df0 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29  3_int64 *pRowid)
30e00 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74  ;.  int (*xUpdat
30e10 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
30e20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
30e30 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65  value **, sqlite
30e40 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e  3_int64 *);.  in
30e50 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69  t (*xBegin)(sqli
30e60 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
30e70 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
30e80 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
30e90 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
30ea0 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f  Commit)(sqlite3_
30eb0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
30ec0 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29  int (*xRollback)
30ed0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
30ee0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
30ef0 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71  FindFunction)(sq
30f00 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
30f10 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e  b, int nArg, con
30f20 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a  st char *zName,.
30f30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30f40 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70         void (**p
30f50 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
30f60 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
30f70 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
30f80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30f90 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72       void **ppAr
30fa0 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e  g);.  int (*xRen
30fb0 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ame)(sqlite3_vta
30fc0 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20  b *pVtab, const 
30fd0 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a  char *zNew);.};.
30fe0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30ff0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
31000 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74  ndexing Informat
31010 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ion.** KEYWORDS:
31020 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
31030 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nfo.**.** The sq
31040 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
31050 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 69   structure and i
31060 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65 73  ts substructures
31070 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70   is used to.** p
31080 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ass information 
31090 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65  into and receive
310a0 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20   the reply from 
310b0 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d  the [xBestIndex]
310c0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20  .** method of a 
310d0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
310e0 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65  odule].  The fie
310f0 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75  lds under **Inpu
31100 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20  ts** are the.** 
31110 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49  inputs to xBestI
31120 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61  ndex and are rea
31130 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e  d-only.  xBestIn
31140 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a  dex inserts its.
31150 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
31160 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20  the **Outputs** 
31170 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  fields..**.** ^(
31180 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
31190 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20  ] array records 
311a0 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
311b0 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20  straints of the 
311c0 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  form:.**.** <pre
311d0 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c  >column OP expr<
311e0 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72  /pre>.**.** wher
311f0 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c  e OP is =, &lt;,
31200 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72   &lt;=, &gt;, or
31210 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65   &gt;=.)^  ^(The
31220 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72   particular oper
31230 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65  ator is.** store
31240 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  d in aConstraint
31250 5b 5d 2e 6f 70 2e 29 5e 20 20 5e 28 54 68 65 20  [].op.)^  ^(The 
31260 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
31270 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e  umn is stored in
31280 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  .** aConstraint[
31290 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28  ].iColumn.)^  ^(
312a0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73  aConstraint[].us
312b0 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 20  able is TRUE if 
312c0 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74  the.** expr on t
312d0 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69  he right-hand si
312e0 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61  de can be evalua
312f0 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 68  ted (and thus th
31300 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  e constraint.** 
31310 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66  is usable) and f
31320 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f  alse if it canno
31330 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  t.)^.**.** ^The 
31340 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61  optimizer automa
31350 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20  tically inverts 
31360 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72  terms of the for
31370 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d  m "expr OP colum
31380 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20  n".** and makes 
31390 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61  other simplifica
313a0 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45  tions to the WHE
313b0 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20  RE clause in an 
313c0 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65  attempt to.** ge
313d0 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20  t as many WHERE 
313e0 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74  clause terms int
313f0 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e  o the form shown
31400 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62   above as possib
31410 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e  le..** ^The aCon
31420 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
31430 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45  only reports WHE
31440 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20  RE clause terms 
31450 74 68 61 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65  that are.** rele
31460 76 61 6e 74 20 74 6f 20 74 68 65 20 70 61 72 74  vant to the part
31470 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74  icular virtual t
31480 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69  able being queri
31490 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72  ed..**.** ^Infor
314a0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
314b0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
314c0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f   is stored in aO
314d0 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61  rderBy[]..** ^Ea
314e0 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65  ch term of aOrde
314f0 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f  rBy records a co
31500 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45  lumn of the ORDE
31510 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a  R BY clause..**.
31520 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64  ** The [xBestInd
31530 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  ex] method must 
31540 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74  fill aConstraint
31550 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66  Usage[] with inf
31560 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
31570 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72  t what parameter
31580 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69  s to pass to xFi
31590 6c 74 65 72 2e 20 20 5e 49 66 20 61 72 67 76 49  lter.  ^If argvI
315a0 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74  ndex>0 then.** t
315b0 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69  he right-hand si
315c0 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73  de of the corres
315d0 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61  ponding aConstra
315e0 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74  int[] is evaluat
315f0 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65  ed.** and become
31600 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d  s the argvIndex-
31610 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76  th entry in argv
31620 2e 20 20 5e 28 49 66 20 61 43 6f 6e 73 74 72 61  .  ^(If aConstra
31630 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a  intUsage[].omit.
31640 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e  ** is true, then
31650 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
31660 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65  is assumed to be
31670 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62   fully handled b
31680 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c  y the.** virtual
31690 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f   table and is no
316a0 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20  t checked again 
316b0 62 79 20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a  by SQLite.)^.**.
316c0 2a 2a 20 5e 54 68 65 20 69 64 78 4e 75 6d 20 61  ** ^The idxNum a
316d0 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73  nd idxPtr values
316e0 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e   are recorded an
316f0 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  d passed into th
31700 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d  e.** [xFilter] m
31710 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69  ethod..** ^[sqli
31720 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75  te3_free()] is u
31730 73 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50  sed to free idxP
31740 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  tr if and only i
31750 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49  f.** needToFreeI
31760 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a  dxPtr is true..*
31770 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72 64 65 72 42  *.** ^The orderB
31780 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20  yConsumed means 
31790 74 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d  that output from
317a0 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78   [xFilter]/[xNex
317b0 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e  t] will occur in
317c0 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20  .** the correct 
317d0 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79  order to satisfy
317e0 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
317f0 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20  ause so that no 
31800 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74  separate.** sort
31810 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75  ing step is requ
31820 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
31830 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76   estimatedCost v
31840 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d  alue is an estim
31850 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20  ate of the cost 
31860 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20  of doing the.** 
31870 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75  particular looku
31880 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20  p.  A full scan 
31890 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 20  of a table with 
318a0 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
318b0 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20   have.** a cost 
318c0 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20  of N.  A binary 
318d0 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c  search of a tabl
318e0 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73  e of N entries s
318f0 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20  hould have a.** 
31900 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d  cost of approxim
31910 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f  ately log(N)..*/
31920 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
31930 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f  index_info {.  /
31940 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e  * Inputs */.  in
31950 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20  t nConstraint;  
31960 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
31970 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e  er of entries in
31980 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a   aConstraint */.
31990 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
319a0 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e  _index_constrain
319b0 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f  t {.     int iCo
319c0 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20  lumn;           
319d0 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20     /* Column on 
319e0 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
319f0 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a  f constraint */.
31a00 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
31a10 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f  ar op;         /
31a20 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65  * Constraint ope
31a30 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e  rator */.     un
31a40 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61 62  signed char usab
31a50 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20  le;     /* True 
31a60 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  if this constrai
31a70 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a  nt is usable */.
31a80 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66       int iTermOf
31a90 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f  fset;          /
31aa0 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  * Used internall
31ab0 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73  y - xBestIndex s
31ac0 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a  hould ignore */.
31ad0 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74    } *aConstraint
31ae0 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
31af0 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63  Table of WHERE c
31b00 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
31b10 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65  s */.  int nOrde
31b20 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20  rBy;            
31b30 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74    /* Number of t
31b40 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45  erms in the ORDE
31b50 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20  R BY clause */. 
31b60 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
31b70 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a  index_orderby {.
31b80 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
31b90 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
31ba0 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20  * Column number 
31bb0 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
31bc0 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20   char desc;     
31bd0 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45    /* True for DE
31be0 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41  SC.  False for A
31bf0 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64  SC. */.  } *aOrd
31c00 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20  erBy;           
31c10 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52      /* The ORDER
31c20 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20   BY clause */.  
31c30 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20  /* Outputs */.  
31c40 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
31c50 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f  ndex_constraint_
31c60 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20  usage {.    int 
31c70 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20  argvIndex;      
31c80 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63       /* if >0, c
31c90 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 72  onstraint is par
31ca0 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69  t of argv to xFi
31cb0 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69  lter */.    unsi
31cc0 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20  gned char omit; 
31cd0 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63       /* Do not c
31ce0 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 74  ode a test for t
31cf0 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a  his constraint *
31d00 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69  /.  } *aConstrai
31d10 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69  ntUsage;.  int i
31d20 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20  dxNum;          
31d30 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
31d40 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79  used to identify
31d50 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20   the index */.  
31d60 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20  char *idxStr;   
31d70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
31d80 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f  ring, possibly o
31d90 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
31da0 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20  ite3_malloc */. 
31db0 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49   int needToFreeI
31dc0 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46  dxStr;      /* F
31dd0 72 65 65 20 69 64 78 53 74 72 20 75 73 69 6e 67  ree idxStr using
31de0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
31df0 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74  if true */.  int
31e00 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64   orderByConsumed
31e10 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20  ;       /* True 
31e20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72  if output is alr
31e30 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a  eady ordered */.
31e40 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74    double estimat
31e50 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20  edCost;      /* 
31e60 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f  Estimated cost o
31e70 66 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64  f using this ind
31e80 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65  ex */.};.#define
31e90 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
31ea0 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32  NSTRAINT_EQ    2
31eb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31ec0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
31ed0 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65  _GT    4.#define
31ee0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
31ef0 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38  NSTRAINT_LE    8
31f00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31f10 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
31f20 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e  _LT    16.#defin
31f30 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
31f40 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20  ONSTRAINT_GE    
31f50 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  32.#define SQLIT
31f60 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
31f70 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a  NT_MATCH 64../*.
31f80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
31f90 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20  ister A Virtual 
31fa0 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61  Table Implementa
31fb0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
31fc0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
31fd0 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  sed to register 
31fe0 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74  a new [virtual t
31ff0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d  able module] nam
32000 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61  e..** ^Module na
32010 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67 69  mes must be regi
32020 73 74 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a  stered before.**
32030 20 63 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20   creating a new 
32040 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20  [virtual table] 
32050 75 73 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65  using the module
32060 20 61 6e 64 20 62 65 66 6f 72 65 20 75 73 69 6e   and before usin
32070 67 20 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69  g a.** preexisti
32080 6e 67 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ng [virtual tabl
32090 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  e] for the modul
320a0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f  e..**.** ^The mo
320b0 64 75 6c 65 20 6e 61 6d 65 20 69 73 20 72 65 67  dule name is reg
320c0 69 73 74 65 72 65 64 20 6f 6e 20 74 68 65 20 5b  istered on the [
320d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
320e0 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 0a 2a  ion] specified.*
320f0 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  * by the first p
32100 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20  arameter.  ^The 
32110 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  name of the modu
32120 6c 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74  le is given by t
32130 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  he .** second pa
32140 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 74  rameter.  ^The t
32150 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
32160 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
32170 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
32180 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69 72  tion of the [vir
32190 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
321a0 65 5d 2e 20 20 20 5e 54 68 65 20 66 6f 75 72 74  e].   ^The fourt
321b0 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  h.** parameter i
321c0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 63  s an arbitrary c
321d0 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74  lient data point
321e0 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  er that is passe
321f0 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74  d through.** int
32200 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65 5d 20  o the [xCreate] 
32210 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d  and [xConnect] m
32220 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 76 69  ethods of the vi
32230 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
32240 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77  le.** when a new
32250 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
32260 73 20 62 65 20 62 65 69 6e 67 20 63 72 65 61 74  s be being creat
32270 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61 6c 69  ed or reinitiali
32280 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  zed..**.** ^The 
32290 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
322a0 6f 64 75 6c 65 5f 76 32 28 29 20 69 6e 74 65 72  odule_v2() inter
322b0 66 61 63 65 20 68 61 73 20 61 20 66 69 66 74 68  face has a fifth
322c0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
322d0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
322e0 20 74 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72   to a destructor
322f0 20 66 6f 72 20 74 68 65 20 70 43 6c 69 65 6e 74   for the pClient
32300 44 61 74 61 2e 20 20 5e 53 51 4c 69 74 65 20 77  Data.  ^SQLite w
32310 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ill.** invoke th
32320 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  e destructor fun
32330 63 74 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20  ction (if it is 
32340 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53  not NULL) when S
32350 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67  QLite.** no long
32360 65 72 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c  er needs the pCl
32370 69 65 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72  ientData pointer
32380 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
32390 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a  create_module().
323a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
323b0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 71  equivalent to sq
323c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
323d0 75 6c 65 5f 76 32 28 29 20 77 69 74 68 20 61 20  ule_v2() with a 
323e0 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74  NULL.** destruct
323f0 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
32400 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
32410 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
32420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
32430 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
32440 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
32450 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
32460 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
32470 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
32480 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
32490 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
324a0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20  ite3_module *p, 
324b0 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
324c0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
324d0 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61   void *pClientDa
324e0 74 61 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43  ta          /* C
324f0 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
32500 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
32510 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
32520 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
32530 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
32540 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
32550 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65   /* SQLite conne
32560 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65  ction to registe
32570 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f  r module with */
32580 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
32590 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a  Name,         /*
325a0 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   Name of the mod
325b0 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  ule */.  const s
325c0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70  qlite3_module *p
325d0 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  ,   /* Methods f
325e0 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  or the module */
325f0 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74  .  void *pClient
32600 44 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a  Data,         /*
32610 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72   Client data for
32620 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63   xCreate/xConnec
32630 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65  t */.  void(*xDe
32640 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20  stroy)(void*)   
32650 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74    /* Module dest
32660 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
32670 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
32680 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
32690 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62  able Instance Ob
326a0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
326b0 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a  : sqlite3_vtab.*
326c0 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74  *.** Every [virt
326d0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
326e0 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ] implementation
326f0 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73   uses a subclass
32700 0a 2a 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  .** of this obje
32710 63 74 20 74 6f 20 64 65 73 63 72 69 62 65 20 61  ct to describe a
32720 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74   particular inst
32730 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ance.** of the [
32740 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20  virtual table]. 
32750 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77   Each subclass w
32760 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72  ill.** be tailor
32770 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  ed to the specif
32780 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20  ic needs of the 
32790 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
327a0 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75  ation..** The pu
327b0 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75  rpose of this su
327c0 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64  perclass is to d
327d0 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69  efine certain fi
327e0 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  elds that are.**
327f0 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d   common to all m
32800 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
32810 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69  tions..**.** ^Vi
32820 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74  rtual tables met
32830 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20  hods can set an 
32840 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79  error message by
32850 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20   assigning a.** 
32860 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
32870 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
32880 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72  rintf()] to zErr
32890 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64  Msg.  The method
328a0 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20   should.** take 
328b0 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72  care that any pr
328c0 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72  ior string is fr
328d0 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f  eed by a call to
328e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
328f0 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73  ].** prior to as
32900 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74  signing a new st
32910 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e  ring to zErrMsg.
32920 20 20 5e 41 66 74 65 72 20 74 68 65 20 65 72 72    ^After the err
32930 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73  or message.** is
32940 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f   delivered up to
32950 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c   the client appl
32960 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72  ication, the str
32970 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ing will be auto
32980 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65  matically.** fre
32990 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72  ed by sqlite3_fr
329a0 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72  ee() and the zEr
329b0 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20  rMsg field will 
329c0 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74  be zeroed..*/.st
329d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
329e0 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69  b {.  const sqli
329f0 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64  te3_module *pMod
32a00 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64  ule;  /* The mod
32a10 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 72  ule for this vir
32a20 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20  tual table */.  
32a30 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20  int nRef;       
32a40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32a50 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45  /* NO LONGER USE
32a60 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72  D */.  char *zEr
32a70 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20  rMsg;           
32a80 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
32a90 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c  message from sql
32aa0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a  ite3_mprintf() *
32ab0 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
32ac0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
32ad0 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
32ae0 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
32af0 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
32b00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32b10 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43   Virtual Table C
32b20 75 72 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20  ursor Object.** 
32b30 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
32b40 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76  3_vtab_cursor {v
32b50 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72  irtual table cur
32b60 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  sor}.**.** Every
32b70 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
32b80 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e  module] implemen
32b90 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75  tation uses a su
32ba0 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
32bb0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
32bc0 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 62 65  ture to describe
32bd0 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f   cursors that po
32be0 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  int into the.** 
32bf0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20  [virtual table] 
32c00 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20  and are used.** 
32c10 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20  to loop through 
32c20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
32c30 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20  e.  Cursors are 
32c40 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
32c50 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f  e.** [sqlite3_mo
32c60 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70  dule.xOpen | xOp
32c70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  en] method of th
32c80 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65  e module and are
32c90 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79   destroyed.** by
32ca0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f   the [sqlite3_mo
32cb0 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43  dule.xClose | xC
32cc0 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43  lose] method.  C
32cd0 75 72 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a  ursors are used.
32ce0 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74  ** by the [xFilt
32cf0 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78  er], [xNext], [x
32d00 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c  Eof], [xColumn],
32d10 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65   and [xRowid] me
32d20 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20  thods.** of the 
32d30 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f  module.  Each mo
32d40 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
32d50 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a  ion will define.
32d60 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
32d70 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63  f a cursor struc
32d80 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73  ture to suit its
32d90 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a   own needs..**.*
32da0 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73  * This superclas
32db0 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65  s exists in orde
32dc0 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c  r to define fiel
32dd0 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72  ds of the cursor
32de0 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d   that.** are com
32df0 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65  mon to all imple
32e00 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73  mentations..*/.s
32e10 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
32e20 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71  ab_cursor {.  sq
32e30 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
32e40 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75  b;      /* Virtu
32e50 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73  al table of this
32e60 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20   cursor */.  /* 
32e70 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
32e80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
32e90 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64  ll typically add
32ea0 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
32eb0 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  ds */.};../*.** 
32ec0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
32ed0 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20  e The Schema Of 
32ee0 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a  A Virtual Table.
32ef0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65  **.** ^The [xCre
32f00 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65  ate] and [xConne
32f10 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61  ct] methods of a
32f20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
32f30 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20  le module] call 
32f40 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a  this interface.*
32f50 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65  * to declare the
32f60 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d   format (the nam
32f70 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73  es and datatypes
32f80 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29   of the columns)
32f90 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75   of.** the virtu
32fa0 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 69  al tables they i
32fb0 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74  mplement..*/.int
32fc0 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65   sqlite3_declare
32fd0 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20  _vtab(sqlite3*, 
32fe0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c  const char *zSQL
32ff0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33000 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46  EF: Overload A F
33010 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69  unction For A Vi
33020 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a  rtual Table.**.*
33030 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 61 62 6c  * ^(Virtual tabl
33040 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61  es can provide a
33050 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65  lternative imple
33060 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75  mentations of fu
33070 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67  nctions.** using
33080 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74   the [xFindFunct
33090 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74  ion] method of t
330a0 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  he [virtual tabl
330b0 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20  e module].  .** 
330c0 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  But global versi
330d0 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e  ons of those fun
330e0 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65  ctions.** must e
330f0 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  xist in order to
33100 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 29   be overloaded.)
33110 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 41  ^.**.** ^(This A
33120 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20  PI makes sure a 
33130 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f  global version o
33140 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  f a function wit
33150 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
33160 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65  * name and numbe
33170 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20  r of parameters 
33180 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73  exists.  If no s
33190 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69  uch function exi
331a0 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  sts.** before th
331b0 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64  is API is called
331c0 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  , a new function
331d0 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e 20 20   is created.)^  
331e0 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ^The implementat
331f0 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65  ion.** of the ne
33200 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79  w function alway
33210 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 65  s causes an exce
33220 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f  ption to be thro
33230 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e  wn.  So.** the n
33240 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e  ew function is n
33250 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74  ot good for anyt
33260 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20  hing by itself. 
33270 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72   Its only.** pur
33280 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 20  pose is to be a 
33290 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e 63  placeholder func
332a0 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65  tion that can be
332b0 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62   overloaded.** b
332c0 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  y a [virtual tab
332d0 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  le]..*/.int sqli
332e0 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e  te3_overload_fun
332f0 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20  ction(sqlite3*, 
33300 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
33310 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29  cName, int nArg)
33320 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  ;../*.** The int
33330 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
33340 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
33350 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62  anism defined ab
33360 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20  ove (back up.** 
33370 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d  to a comment rem
33380 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20  arkably similar 
33390 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20  to this one) is 
333a0 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
333b0 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
333c0 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
333d0 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
333e0 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
333f0 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
33400 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
33410 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
33420 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
33430 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
33440 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
33450 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
33460 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
33470 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c  bilizes, we will
33480 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20   declare the.** 
33490 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c  interface fixed,
334a0 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65   support it inde
334b0 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65  finitely, and re
334c0 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e  move this commen
334d0 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t..*/../*.** CAP
334e0 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20  I3REF: A Handle 
334f0 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a  To An Open BLOB.
33500 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c  ** KEYWORDS: {BL
33510 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42  OB handle} {BLOB
33520 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20   handles}.**.** 
33530 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
33540 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
33550 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c  sents an open BL
33560 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b  OB on which.** [
33570 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
33580 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
33590 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65  BLOB I/O] can be
335a0 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e   performed..** ^
335b0 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20  Objects of this 
335c0 74 79 70 65 20 61 72 65 20 63 72 65 61 74 65 64  type are created
335d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
335e0 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64  b_open()].** and
335f0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
33600 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
33610 65 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  e()]..** ^The [s
33620 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
33630 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
33640 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69  _blob_write()] i
33650 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e  nterfaces.** can
33660 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64   be used to read
33670 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20   or write small 
33680 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74  subsections of t
33690 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65  he BLOB..** ^The
336a0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
336b0 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
336c0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  e returns the si
336d0 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69  ze of the BLOB i
336e0 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65  n bytes..*/.type
336f0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
33700 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f  e3_blob sqlite3_
33710 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  blob;../*.** CAP
33720 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c  I3REF: Open A BL
33730 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74  OB For Increment
33740 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54  al I/O.**.** ^(T
33750 68 69 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f  his interfaces o
33760 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e  pens a [BLOB han
33770 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f  dle | handle] to
33780 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65   the BLOB locate
33790 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77  d.** in row iRow
337a0 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e  , column zColumn
337b0 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69  , table zTable i
337c0 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a  n database zDb;.
337d0 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** in other word
337e0 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42  s, the same BLOB
337f0 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73   that would be s
33800 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a  elected by:.**.*
33810 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53  * <pre>.**     S
33820 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52  ELECT zColumn FR
33830 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48  OM zDb.zTable WH
33840 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52  ERE [rowid] = iR
33850 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a  ow;.** </pre>)^.
33860 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c  **.** ^If the fl
33870 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  ags parameter is
33880 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
33890 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e  the BLOB is open
338a0 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61  ed for read.** a
338b0 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e  nd write access.
338c0 20 5e 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c   ^If it is zero,
338d0 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65   the BLOB is ope
338e0 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61 63 63  ned for read acc
338f0 65 73 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e  ess..** ^It is n
33900 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f  ot possible to o
33910 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61  pen a column tha
33920 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 6e 20  t is part of an 
33930 69 6e 64 65 78 20 6f 72 20 70 72 69 6d 61 72 79  index or primary
33940 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72 69   .** key for wri
33950 74 69 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69  ting. ^If [forei
33960 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
33970 74 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 2c  ts] are enabled,
33980 20 69 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70   it is .** not p
33990 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20  ossible to open 
339a0 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  a column that is
339b0 20 70 61 72 74 20 6f 66 20 61 20 5b 63 68 69 6c   part of a [chil
339c0 64 20 6b 65 79 5d 20 66 6f 72 20 77 72 69 74 69  d key] for writi
339d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  ng..**.** ^Note 
339e0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
339f0 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68  e name is not th
33a00 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20  e filename that 
33a10 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
33a20 64 61 74 61 62 61 73 65 20 62 75 74 20 72 61 74  database but rat
33a30 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63  her the symbolic
33a40 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
33a50 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 61 70  abase that.** ap
33a60 70 65 61 72 73 20 61 66 74 65 72 20 74 68 65 20  pears after the 
33a70 41 53 20 6b 65 79 77 6f 72 64 20 77 68 65 6e 20  AS keyword when 
33a80 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
33a90 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20  connected using 
33aa0 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f  [ATTACH]..** ^Fo
33ab0 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  r the main datab
33ac0 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61  ase file, the da
33ad0 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22  tabase name is "
33ae0 6d 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54  main"..** ^For T
33af0 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20  EMP tables, the 
33b00 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73  database name is
33b10 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e   "temp"..**.** ^
33b20 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51  (On success, [SQ
33b30 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
33b40 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77  rned and the new
33b50 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69   [BLOB handle] i
33b60 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20  s written.** to 
33b70 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69  *ppBlob. Otherwi
33b80 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
33b90 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  e] is returned a
33ba0 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65  nd *ppBlob is se
33bb0 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c  t.** to be a nul
33bc0 6c 20 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20  l pointer.)^.** 
33bd0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73  ^This function s
33be0 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  ets the [databas
33bf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72  e connection] er
33c00 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
33c10 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62  sage.** accessib
33c20 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  le via [sqlite3_
33c30 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b  errcode()] and [
33c40 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
33c50 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a  ] and related.**
33c60 20 66 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74   functions. ^Not
33c70 65 20 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c  e that the *ppBl
33c80 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  ob variable is a
33c90 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65  lways initialize
33ca0 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68  d in a.** way th
33cb0 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65  at makes it safe
33cc0 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69   to invoke [sqli
33cd0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
33ce0 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20  ] on *ppBlob.** 
33cf0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
33d00 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69  e success or fai
33d10 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75  lure of this rou
33d20 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  tine..**.** ^(If
33d30 20 74 68 65 20 72 6f 77 20 74 68 61 74 20 61 20   the row that a 
33d40 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e  BLOB handle poin
33d50 74 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65  ts to is modifie
33d60 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41  d by an.** [UPDA
33d70 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f  TE], [DELETE], o
33d80 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  r by [ON CONFLIC
33d90 54 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a  T] side-effects.
33da0 2a 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42  ** then the BLOB
33db0 20 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65   handle is marke
33dc0 64 20 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a  d as "expired"..
33dd0 2a 2a 20 54 68 69 73 20 69 73 20 74 72 75 65 20  ** This is true 
33de0 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66  if any column of
33df0 20 74 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e   the row is chan
33e00 67 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75  ged, even a colu
33e10 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  mn.** other than
33e20 20 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f   the one the BLO
33e30 42 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e  B handle is open
33e40 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73   on.)^.** ^Calls
33e50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
33e60 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73  b_read()] and [s
33e70 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
33e80 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78  e()] for.** a ex
33e90 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c  pired BLOB handl
33ea0 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 72  e fail with an r
33eb0 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53  eturn code of [S
33ec0 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
33ed0 20 5e 28 43 68 61 6e 67 65 73 20 77 72 69 74 74   ^(Changes writt
33ee0 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70  en into a BLOB p
33ef0 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42  rior to the BLOB
33f00 20 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f   expiring are no
33f10 74 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t.** rolled back
33f20 20 62 79 20 74 68 65 20 65 78 70 69 72 61 74 69   by the expirati
33f30 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20  on of the BLOB. 
33f40 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 77 69   Such changes wi
33f50 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a  ll eventually.**
33f60 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74   commit if the t
33f70 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69  ransaction conti
33f80 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
33f90 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65  on.)^.**.** ^Use
33fa0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   the [sqlite3_bl
33fb0 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65  ob_bytes()] inte
33fc0 72 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69  rface to determi
33fd0 6e 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  ne the size of.*
33fe0 2a 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f  * the opened blo
33ff0 62 2e 20 20 5e 54 68 65 20 73 69 7a 65 20 6f 66  b.  ^The size of
34000 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20   a blob may not 
34010 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 74 68  be changed by th
34020 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  is.** interface.
34030 20 20 55 73 65 20 74 68 65 20 5b 55 50 44 41 54    Use the [UPDAT
34040 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74  E] SQL command t
34050 6f 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a  o change the siz
34060 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a  e of a.** blob..
34070 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
34080 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
34090 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  b()] and [sqlite
340a0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
340b0 62 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a  b()] interfaces.
340c0 2a 2a 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74  ** and the built
340d0 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53  -in [zeroblob] S
340e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  QL function can 
340f0 62 65 20 75 73 65 64 2c 20 69 66 20 64 65 73 69  be used, if desi
34100 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74  red,.** to creat
34110 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f  e an empty, zero
34120 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20  -filled blob in 
34130 77 68 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72  which to read or
34140 20 77 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20   write using.** 
34150 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
34160 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61  **.** To avoid a
34170 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20   resource leak, 
34180 65 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42  every open [BLOB
34190 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20   handle] should 
341a0 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65  eventually.** be
341b0 20 72 65 6c 65 61 73 65 64 20 62 79 20 61 20 63   released by a c
341c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
341d0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  blob_close()]..*
341e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
341f0 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74  ob_open(.  sqlit
34200 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  e3*,.  const cha
34210 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20  r *zDb,.  const 
34220 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20  char *zTable,.  
34230 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
34240 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69  umn,.  sqlite3_i
34250 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74  nt64 iRow,.  int
34260 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65   flags,.  sqlite
34270 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a  3_blob **ppBlob.
34280 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34290 45 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42  EF: Close A BLOB
342a0 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43   Handle.**.** ^C
342b0 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42  loses an open [B
342c0 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a  LOB handle]..**.
342d0 2a 2a 20 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c  ** ^Closing a BL
342e0 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74  OB shall cause t
342f0 68 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  he current trans
34300 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74  action to commit
34310 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65  .** if there are
34320 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c   no other BLOBs,
34330 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70   no pending prep
34340 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c  ared statements,
34350 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61   and the.** data
34360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34370 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69  is in [autocommi
34380 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20  t mode]..** ^If 
34390 61 6e 79 20 77 72 69 74 65 73 20 77 65 72 65 20  any writes were 
343a0 6d 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42  made to the BLOB
343b0 2c 20 74 68 65 79 20 6d 69 67 68 74 20 62 65 20  , they might be 
343c0 68 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a  held in cache.**
343d0 20 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65   until the close
343e0 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68   operation if th
343f0 65 79 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a  ey will fit..**.
34400 2a 2a 20 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65  ** ^(Closing the
34410 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63   BLOB often forc
34420 65 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a  es the changes.*
34430 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e  * out to disk an
34440 64 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20  d so if any I/O 
34450 65 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68  errors occur, th
34460 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f  ey will likely o
34470 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74  ccur.** at the t
34480 69 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f  ime when the BLO
34490 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e  B is closed.  An
344a0 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  y errors that oc
344b0 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c  cur during.** cl
344c0 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74  osing are report
344d0 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  ed as a non-zero
344e0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e   return value.)^
344f0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f  .**.** ^(The BLO
34500 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f  B is closed unco
34510 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76  nditionally.  Ev
34520 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74 69  en if this routi
34530 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ne returns.** an
34540 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65   error code, the
34550 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63   BLOB is still c
34560 6c 6f 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  losed.)^.**.** ^
34570 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
34580 74 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c  tine with a null
34590 20 70 6f 69 6e 74 65 72 20 28 73 75 63 68 20 61   pointer (such a
345a0 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72  s would be retur
345b0 6e 65 64 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c  ned.** by a fail
345c0 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ed call to [sqli
345d0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
345e0 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  ) is a harmless 
345f0 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71  no-op..*/.int sq
34600 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
34610 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
34620 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34630 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53 69  F: Return The Si
34640 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c  ze Of An Open BL
34650 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  OB.**.** ^Return
34660 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79  s the size in by
34670 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  tes of the BLOB 
34680 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74  accessible via t
34690 68 65 20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  he .** successfu
346a0 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42  lly opened [BLOB
346b0 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20   handle] in its 
346c0 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 20  only argument.  
346d0 5e 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e  ^The.** incremen
346e0 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75  tal blob I/O rou
346f0 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72  tines can only r
34700 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69  ead or overwriti
34710 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62  ng existing.** b
34720 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65  lob content; the
34730 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  y cannot change 
34740 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c  the size of a bl
34750 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ob..**.** This r
34760 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b  outine only work
34770 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e  s on a [BLOB han
34780 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62  dle] which has b
34790 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62  een created.** b
347a0 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  y a prior succes
347b0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
347c0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
347d0 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73  )] and which has
347e0 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f   not.** been clo
347f0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
34800 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20  blob_close()].  
34810 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  Passing any othe
34820 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20  r pointer in.** 
34830 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
34840 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
34850 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
34860 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  y undesirable be
34870 68 61 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73  havior..*/.int s
34880 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
34890 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  s(sqlite3_blob *
348a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
348b0 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 72  EF: Read Data Fr
348c0 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  om A BLOB Increm
348d0 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28  entally.**.** ^(
348e0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
348f0 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 61   used to read da
34900 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20  ta from an open 
34910 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e  [BLOB handle] in
34920 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73  to a.** caller-s
34930 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20  upplied buffer. 
34940 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
34950 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
34960 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d  buffer Z.** from
34970 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20   the open BLOB, 
34980 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73  starting at offs
34990 65 74 20 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a  et iOffset.)^.**
349a0 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69  .** ^If offset i
349b0 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74  Offset is less t
349c0 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d  han N bytes from
349d0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
349e0 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  BLOB,.** [SQLITE
349f0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
34a00 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
34a10 69 73 20 72 65 61 64 2e 20 20 5e 49 66 20 4e 20  is read.  ^If N 
34a20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a  or iOffset is.**
34a30 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
34a40 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
34a50 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
34a60 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e  no data is read.
34a70 0a 2a 2a 20 5e 54 68 65 20 73 69 7a 65 20 6f 66  .** ^The size of
34a80 20 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68   the blob (and h
34a90 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d  ence the maximum
34aa0 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66   value of N+iOff
34ab0 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64  set).** can be d
34ac0 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20  etermined using 
34ad0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
34ae0 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
34af0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  face..**.** ^An 
34b00 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
34b10 66 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20  from an expired 
34b20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61  [BLOB handle] fa
34b30 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65  ils with an.** e
34b40 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
34b50 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a  LITE_ABORT]..**.
34b60 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c  ** ^(On success,
34b70 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65   sqlite3_blob_re
34b80 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
34b90 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72  ITE_OK..** Other
34ba0 77 69 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20  wise, an [error 
34bb0 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74  code] or an [ext
34bc0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
34bd0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
34be0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
34bf0 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f  ine only works o
34c00 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  n a [BLOB handle
34c10 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e  ] which has been
34c20 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61   created.** by a
34c30 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
34c40 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
34c50 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
34c60 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f  and which has no
34c70 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64  t.** been closed
34c80 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
34c90 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73  b_close()].  Pas
34ca0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70  sing any other p
34cb0 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20  ointer in.** to 
34cc0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73  this routine res
34cd0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
34ce0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
34cf0 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
34d00 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ior..**.** See a
34d10 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  lso: [sqlite3_bl
34d20 6f 62 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a  ob_write()]..*/.
34d30 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
34d40 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c  _read(sqlite3_bl
34d50 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69  ob *, void *Z, i
34d60 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65  nt N, int iOffse
34d70 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
34d80 52 45 46 3a 20 57 72 69 74 65 20 44 61 74 61 20  REF: Write Data 
34d90 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72  Into A BLOB Incr
34da0 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20  ementally.**.** 
34db0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69  ^This function i
34dc0 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20  s used to write 
34dd0 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65  data into an ope
34de0 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  n [BLOB handle] 
34df0 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72  from a.** caller
34e00 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72  -supplied buffer
34e10 2e 20 5e 4e 20 62 79 74 65 73 20 6f 66 20 64 61  . ^N bytes of da
34e20 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66 72  ta are copied fr
34e30 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a  om the buffer Z.
34e40 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e  ** into the open
34e50 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20   BLOB, starting 
34e60 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  at offset iOffse
34e70 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  t..**.** ^If the
34e80 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70   [BLOB handle] p
34e90 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
34ea0 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20  st argument was 
34eb0 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a  not opened for.*
34ec0 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66  * writing (the f
34ed0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
34ee0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
34ef0 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f  open()] was zero
34f00 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  ),.** this funct
34f10 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ion returns [SQL
34f20 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a  ITE_READONLY]..*
34f30 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
34f40 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64  ion may only mod
34f50 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73  ify the contents
34f60 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74   of the BLOB; it
34f70 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69   is.** not possi
34f80 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20  ble to increase 
34f90 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c  the size of a BL
34fa0 4f 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 50  OB using this AP
34fb0 49 2e 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74  I..** ^If offset
34fc0 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73   iOffset is less
34fd0 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72   than N bytes fr
34fe0 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  om the end of th
34ff0 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49  e BLOB,.** [SQLI
35000 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74  TE_ERROR] is ret
35010 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74  urned and no dat
35020 61 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20 5e  a is written.  ^
35030 49 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20  If N is.** less 
35040 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54  than zero [SQLIT
35050 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
35060 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
35070 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20   is written..** 
35080 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
35090 42 4c 4f 42 20 28 61 6e 64 20 68 65 6e 63 65 20  BLOB (and hence 
350a0 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75  the maximum valu
350b0 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a  e of N+iOffset).
350c0 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
350d0 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
350e0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
350f0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
35100 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d  .**.** ^An attem
35110 70 74 20 74 6f 20 77 72 69 74 65 20 74 6f 20 61  pt to write to a
35120 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20  n expired [BLOB 
35130 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69  handle] fails wi
35140 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63  th an.** error c
35150 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41  ode of [SQLITE_A
35160 42 4f 52 54 5d 2e 20 20 5e 57 72 69 74 65 73 20  BORT].  ^Writes 
35170 74 6f 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74  to the BLOB that
35180 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62 65 66   occurred.** bef
35190 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42 20 68 61  ore the [BLOB ha
351a0 6e 64 6c 65 5d 20 65 78 70 69 72 65 64 20 61 72  ndle] expired ar
351b0 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63  e not rolled bac
351c0 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65 78 70 69  k by the.** expi
351d0 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 68 61  ration of the ha
351e0 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66 20  ndle, though of 
351f0 63 6f 75 72 73 65 20 74 68 6f 73 65 20 63 68 61  course those cha
35200 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61  nges might.** ha
35210 76 65 20 62 65 65 6e 20 6f 76 65 72 77 72 69 74  ve been overwrit
35220 74 65 6e 20 62 79 20 74 68 65 20 73 74 61 74 65  ten by the state
35230 6d 65 6e 74 20 74 68 61 74 20 65 78 70 69 72 65  ment that expire
35240 64 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  d the BLOB handl
35250 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65 72  e.** or by other
35260 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 73 74 61   independent sta
35270 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
35280 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c  (On success, sql
35290 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
352a0 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
352b0 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  _OK..** Otherwis
352c0 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f  e, an  [error co
352d0 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e  de] or an [exten
352e0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
352f0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
35300 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
35310 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  e only works on 
35320 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  a [BLOB handle] 
35330 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63  which has been c
35340 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70  reated.** by a p
35350 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
35360 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
35370 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
35380 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a  d which has not.
35390 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62  ** been closed b
353a0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
353b0 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69  close()].  Passi
353c0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69  ng any other poi
353d0 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68  nter in.** to th
353e0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c  is routine resul
353f0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
35400 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
35410 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
35420 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
35430 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  o: [sqlite3_blob
35440 5f 72 65 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  _read()]..*/.int
35450 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72   sqlite3_blob_wr
35460 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ite(sqlite3_blob
35470 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   *, const void *
35480 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f  z, int n, int iO
35490 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ffset);../*.** C
354a0 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
354b0 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a   File System Obj
354c0 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72  ects.**.** A vir
354d0 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20  tual filesystem 
354e0 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c  (VFS) is an [sql
354f0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
35500 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
35510 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74  uses to interact
35520 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64  .** with the und
35530 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
35540 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20  g system.  Most 
35550 53 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f  SQLite builds co
35560 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e  me with a.** sin
35570 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  gle default VFS 
35580 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69  that is appropri
35590 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74  ate for the host
355a0 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65   computer..** Ne
355b0 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72  w VFSes can be r
355c0 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78  egistered and ex
355d0 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e  isting VFSes can
355e0 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64   be unregistered
355f0 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ..** The followi
35600 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ng interfaces ar
35610 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a  e provided..**.*
35620 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
35630 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66  fs_find() interf
35640 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
35650 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20 67  inter to a VFS g
35660 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a  iven its name..*
35670 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20 63 61 73  * ^Names are cas
35680 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20  e sensitive..** 
35690 5e 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d  ^Names are zero-
356a0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
356b0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66   strings..** ^If
356c0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74   there is no mat
356d0 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ch, a NULL point
356e0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
356f0 2a 2a 20 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20  ** ^If zVfsName 
35700 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
35710 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
35720 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
35730 5e 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72  ^New VFSes are r
35740 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73  egistered with s
35750 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
35760 74 65 72 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20  ter()..** ^Each 
35770 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20  new VFS becomes 
35780 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
35790 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20  if the makeDflt 
357a0 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20  flag is set..** 
357b0 5e 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61  ^The same VFS ca
357c0 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
357d0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77  multiple times w
357e0 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a  ithout injury..*
357f0 2a 20 5e 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78  * ^To make an ex
35800 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20  isting VFS into 
35810 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c  the default VFS,
35820 20 72 65 67 69 73 74 65 72 20 69 74 20 61 67 61   register it aga
35830 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d  in.** with the m
35840 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74  akeDflt flag set
35850 2e 20 20 49 66 20 74 77 6f 20 64 69 66 66 65 72  .  If two differ
35860 65 6e 74 20 56 46 53 65 73 20 77 69 74 68 20 74  ent VFSes with t
35870 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20  he.** same name 
35880 61 72 65 20 72 65 67 69 73 74 65 72 65 64 2c 20  are registered, 
35890 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
358a0 75 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61  undefined.  If a
358b0 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69 73  .** VFS is regis
358c0 74 65 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d  tered with a nam
358d0 65 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f  e that is NULL o
358e0 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
358f0 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  g,.** then the b
35900 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
35910 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72  ined..**.** ^Unr
35920 65 67 69 73 74 65 72 20 61 20 56 46 53 20 77 69  egister a VFS wi
35930 74 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  th the sqlite3_v
35940 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20  fs_unregister() 
35950 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28  interface..** ^(
35960 49 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  If the default V
35970 46 53 20 69 73 20 75 6e 72 65 67 69 73 74 65 72  FS is unregister
35980 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20  ed, another VFS 
35990 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20  is chosen as.** 
359a0 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68  the default.  Th
359b0 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65  e choice for the
359c0 20 6e 65 77 20 56 46 53 20 69 73 20 61 72 62 69   new VFS is arbi
359d0 74 72 61 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69  trary.)^.*/.sqli
359e0 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33  te3_vfs *sqlite3
359f0 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20  _vfs_find(const 
35a00 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b  char *zVfsName);
35a10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73  .int sqlite3_vfs
35a20 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65  _register(sqlite
35a30 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65  3_vfs*, int make
35a40 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74  Dflt);.int sqlit
35a50 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
35a60 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b  r(sqlite3_vfs*);
35a70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35a80 3a 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20  : Mutexes.**.** 
35a90 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
35aa0 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69  uses these routi
35ab0 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a  nes for thread.*
35ac0 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  * synchronizatio
35ad0 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20 61  n. Though they a
35ae0 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
35af0 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20  internal.** use 
35b00 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20  by SQLite, code 
35b10 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
35b20 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  st SQLite is.** 
35b30 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65  permitted to use
35b40 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
35b50 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
35b60 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  e SQLite source 
35b70 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75  code contains mu
35b80 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
35b90 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65  ations.** of the
35ba0 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  se mutex routine
35bb0 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61  s.  An appropria
35bc0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  te implementatio
35bd0 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64  n.** is selected
35be0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61   automatically a
35bf0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20  t compile-time. 
35c00 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
35c10 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
35c20 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
35c30 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
35c40 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  core:.**.** <ul>
35c50 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
35c60 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c  E_MUTEX_OS2.** <
35c70 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
35c80 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c  EX_PTHREAD.** <l
35c90 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
35ca0 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20  X_W32.** <li>   
35cb0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f  SQLITE_MUTEX_NOO
35cc0 50 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  P.** </ul>)^.**.
35cd0 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d  ** ^The SQLITE_M
35ce0 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d  UTEX_NOOP implem
35cf0 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65  entation is a se
35d00 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  t of routines.**
35d10 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65   that does no re
35d20 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69  al locking and i
35d30 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
35d40 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69  r use in.** a si
35d50 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70  ngle-threaded ap
35d60 70 6c 69 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65  plication.  ^The
35d70 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53   SQLITE_MUTEX_OS
35d80 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  2,.** SQLITE_MUT
35d90 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20  EX_PTHREAD, and 
35da0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32  SQLITE_MUTEX_W32
35db0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
35dc0 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69  .** are appropri
35dd0 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f  ate for use on O
35de0 53 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57  S/2, Unix, and W
35df0 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  indows..**.** ^(
35e00 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
35e10 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  piled with the S
35e20 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44  QLITE_MUTEX_APPD
35e30 45 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a  EF preprocessor.
35e40 2a 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  ** macro defined
35e50 20 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45   (with "-DSQLITE
35e60 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22  _MUTEX_APPDEF=1"
35e70 29 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78  ), then no mutex
35e80 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
35e90 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77  on is included w
35ea0 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e  ith the library.
35eb0 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 74 68   In this case th
35ec0 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
35ed0 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 63   must supply a c
35ee0 75 73 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c  ustom mutex impl
35ef0 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67  ementation using
35f00 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
35f10 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70  CONFIG_MUTEX] op
35f20 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c 69  tion of the sqli
35f30 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e  te3_config() fun
35f40 63 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20  ction.** before 
35f50 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
35f60 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 20  initialize() or 
35f70 61 6e 79 20 6f 74 68 65 72 20 70 75 62 6c 69 63  any other public
35f80 20 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e   sqlite3_.** fun
35f90 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73  ction that calls
35fa0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
35fb0 69 7a 65 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ize().)^.**.** ^
35fc0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
35fd0 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  x_alloc() routin
35fe0 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65  e allocates a ne
35ff0 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72  w.** mutex and r
36000 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
36010 20 74 6f 20 69 74 2e 20 5e 49 66 20 69 74 20 72   to it. ^If it r
36020 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74  eturns NULL.** t
36030 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61  hat means that a
36040 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74   mutex could not
36050 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20   be allocated.  
36060 5e 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20  ^SQLite.** will 
36070 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b  unwind its stack
36080 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65   and return an e
36090 72 72 6f 72 2e 20 20 5e 28 54 68 65 20 61 72 67  rror.  ^(The arg
360a0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
360b0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
360c0 29 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  ) is one of thes
360d0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
360e0 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  nts:.**.** <ul>.
360f0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
36100 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c  MUTEX_FAST.** <l
36110 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
36120 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c  _RECURSIVE.** <l
36130 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
36140 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a  _STATIC_MASTER.*
36150 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
36160 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a  UTEX_STATIC_MEM.
36170 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
36180 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
36190 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  2.** <li>  SQLIT
361a0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50  E_MUTEX_STATIC_P
361b0 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RNG.** <li>  SQL
361c0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
361d0 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  _LRU.** <li>  SQ
361e0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
361f0 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29  C_LRU2.** </ul>)
36200 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ^.**.** ^The fir
36210 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  st two constants
36220 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46   (SQLITE_MUTEX_F
36230 41 53 54 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  AST and SQLITE_M
36240 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 0a  UTEX_RECURSIVE).
36250 2a 2a 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  ** cause sqlite3
36260 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74  _mutex_alloc() t
36270 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65  o create.** a ne
36280 77 20 6d 75 74 65 78 2e 20 20 5e 54 68 65 20 6e  w mutex.  ^The n
36290 65 77 20 6d 75 74 65 78 20 69 73 20 72 65 63 75  ew mutex is recu
362a0 72 73 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54  rsive when SQLIT
362b0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
362c0 45 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74  E.** is used but
362d0 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79   not necessarily
362e0 20 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f   so when SQLITE_
362f0 4d 55 54 45 58 5f 46 41 53 54 20 69 73 20 75 73  MUTEX_FAST is us
36300 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  ed..** The mutex
36310 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36320 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
36330 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74   make a distinct
36340 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
36350 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
36360 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45  RSIVE and SQLITE
36370 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20 69  _MUTEX_FAST if i
36380 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  t does.** not wa
36390 6e 74 20 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20  nt to.  ^SQLite 
363a0 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73  will only reques
363b0 74 20 61 20 72 65 63 75 72 73 69 76 65 20 6d 75  t a recursive mu
363c0 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20  tex in.** cases 
363d0 77 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20  where it really 
363e0 6e 65 65 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20  needs one.  ^If 
363f0 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63  a faster non-rec
36400 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20  ursive mutex.** 
36410 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
36420 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74  s available on t
36430 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d  he host platform
36440 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 73  , the mutex subs
36450 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72  ystem.** might r
36460 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74  eturn such a mut
36470 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ex in response t
36480 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  o SQLITE_MUTEX_F
36490 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  AST..**.** ^The 
364a0 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61  other allowed pa
364b0 72 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69  rameters to sqli
364c0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
364d0 29 20 28 61 6e 79 74 68 69 6e 67 20 6f 74 68 65  ) (anything othe
364e0 72 0a 2a 2a 20 74 68 61 6e 20 53 51 4c 49 54 45  r.** than SQLITE
364f0 5f 4d 55 54 45 58 5f 46 41 53 54 20 61 6e 64 20  _MUTEX_FAST and 
36500 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
36510 55 52 53 49 56 45 29 20 65 61 63 68 20 72 65 74  URSIVE) each ret
36520 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  urn.** a pointer
36530 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65   to a static pre
36540 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20  existing mutex. 
36550 20 5e 53 69 78 20 73 74 61 74 69 63 20 6d 75 74   ^Six static mut
36560 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  exes are.** used
36570 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
36580 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
36590 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  e.  Future versi
365a0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
365b0 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f   may add additio
365c0 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78  nal static mutex
365d0 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65  es.  Static mute
365e0 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65  xes are for inte
365f0 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53  rnal.** use by S
36600 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70  QLite only.  App
36610 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
36620 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65  se SQLite mutexe
36630 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20  s should.** use 
36640 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63  only the dynamic
36650 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65   mutexes returne
36660 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45  d by SQLITE_MUTE
36670 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c  X_FAST or.** SQL
36680 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
36690 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  IVE..**.** ^Note
366a0 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20   that if one of 
366b0 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  the dynamic mute
366c0 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51  x parameters (SQ
366d0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a  LITE_MUTEX_FAST.
366e0 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54  ** or SQLITE_MUT
366f0 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73  EX_RECURSIVE) is
36700 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74   used then sqlit
36710 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
36720 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69  .** returns a di
36730 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e  fferent mutex on
36740 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42   every call.  ^B
36750 75 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69  ut for the stati
36760 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73  c.** mutex types
36770 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78  , the same mutex
36780 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20   is returned on 
36790 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20  every call that 
367a0 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  has.** the same 
367b0 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  type number..**.
367c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
367d0 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75  mutex_free() rou
367e0 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73  tine deallocates
367f0 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a   a previously.**
36800 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d   allocated dynam
36810 69 63 20 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69  ic mutex.  ^SQLi
36820 74 65 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f  te is careful to
36830 20 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72   deallocate ever
36840 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74  y.** dynamic mut
36850 65 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63  ex that it alloc
36860 61 74 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d  ates.  The dynam
36870 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20  ic mutexes must 
36880 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65  not be in.** use
36890 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64   when they are d
368a0 65 61 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74  eallocated.  Att
368b0 65 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c  empting to deall
368c0 6f 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a  ocate a static.*
368d0 2a 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20  * mutex results 
368e0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
368f0 61 76 69 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20  avior.  ^SQLite 
36900 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65  never deallocate
36910 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75  s.** a static mu
36920 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tex..**.** ^The 
36930 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
36940 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ter() and sqlite
36950 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f  3_mutex_try() ro
36960 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a  utines attempt.*
36970 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74  * to enter a mut
36980 65 78 2e 20 20 5e 49 66 20 61 6e 6f 74 68 65 72  ex.  ^If another
36990 20 74 68 72 65 61 64 20 69 73 20 61 6c 72 65 61   thread is alrea
369a0 64 79 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75  dy within the mu
369b0 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  tex,.** sqlite3_
369c0 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69  mutex_enter() wi
369d0 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c  ll block and sql
369e0 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
369f0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
36a00 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 5e 54  SQLITE_BUSY.  ^T
36a10 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
36a20 5f 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 65  _try() interface
36a30 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
36a40 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63  _OK].** upon suc
36a50 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20  cessful entry.  
36a60 5e 28 4d 75 74 65 78 65 73 20 63 72 65 61 74 65  ^(Mutexes create
36a70 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54  d using.** SQLIT
36a80 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
36a90 45 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64  E can be entered
36aa0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
36ab0 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  by the same thre
36ac0 61 64 2e 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63  ad..** In such c
36ad0 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74  ases the,.** mut
36ae0 65 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65  ex must be exite
36af0 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65  d an equal numbe
36b00 72 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72  r of times befor
36b10 65 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  e another thread
36b20 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e  .** can enter.)^
36b30 20 20 5e 28 49 66 20 74 68 65 20 73 61 6d 65 20    ^(If the same 
36b40 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20  thread tries to 
36b50 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a  enter any other.
36b60 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78  ** kind of mutex
36b70 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
36b80 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
36b90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53   undefined..** S
36ba0 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
36bb0 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68   exhibit.** such
36bc0 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73   behavior in its
36bd0 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65   own use of mute
36be0 78 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53  xes.)^.**.** ^(S
36bf0 6f 6d 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72  ome systems (for
36c00 20 65 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77   example, Window
36c10 73 20 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70  s 95) do not sup
36c20 70 6f 72 74 20 74 68 65 20 6f 70 65 72 61 74 69  port the operati
36c30 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65  on.** implemente
36c40 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74  d by sqlite3_mut
36c50 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68  ex_try().  On th
36c60 6f 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c  ose systems, sql
36c70 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
36c80 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  .** will always 
36c90 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55  return SQLITE_BU
36ca0 53 59 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  SY.  The SQLite 
36cb0 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75  core only ever u
36cc0 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ses.** sqlite3_m
36cd0 75 74 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e  utex_try() as an
36ce0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f   optimization so
36cf0 20 74 68 69 73 20 69 73 20 61 63 63 65 70 74 61   this is accepta
36d00 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a  ble behavior.)^.
36d10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36d20 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29  e3_mutex_leave()
36d30 20 72 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61   routine exits a
36d40 20 6d 75 74 65 78 20 74 68 61 74 20 77 61 73 0a   mutex that was.
36d50 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e  ** previously en
36d60 74 65 72 65 64 20 62 79 20 74 68 65 20 73 61 6d  tered by the sam
36d70 65 20 74 68 72 65 61 64 2e 20 20 20 5e 28 54 68  e thread.   ^(Th
36d80 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73  e behavior.** is
36d90 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68   undefined if th
36da0 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63  e mutex is not c
36db0 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
36dc0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69   by the.** calli
36dd0 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 20  ng thread or is 
36de0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c  not currently al
36df0 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65  located.  SQLite
36e00 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64   will.** never d
36e10 6f 20 65 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a  o either.)^.**.*
36e20 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65  * ^If the argume
36e30 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  nt to sqlite3_mu
36e40 74 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c  tex_enter(), sql
36e50 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
36e60 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  , or.** sqlite3_
36e70 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73  mutex_leave() is
36e80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
36e90 20 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20   then all three 
36ea0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61  routines.** beha
36eb0 76 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  ve as no-ops..**
36ec0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
36ed0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
36ee0 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
36ef0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
36f00 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d  )]..*/.sqlite3_m
36f10 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75  utex *sqlite3_mu
36f20 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  tex_alloc(int);.
36f30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74  void sqlite3_mut
36f40 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f  ex_free(sqlite3_
36f50 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71  mutex*);.void sq
36f60 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
36f70 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  r(sqlite3_mutex*
36f80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  );.int sqlite3_m
36f90 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33  utex_try(sqlite3
36fa0 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73  _mutex*);.void s
36fb0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
36fc0 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ve(sqlite3_mutex
36fd0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36fe0 52 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f  REF: Mutex Metho
36ff0 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
37000 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
37010 68 69 73 20 73 74 72 75 63 74 75 72 65 20 64 65  his structure de
37020 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65  fines the low-le
37030 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  vel routines.** 
37040 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65  used to allocate
37050 20 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73   and use mutexes
37060 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c  ..**.** Usually,
37070 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
37080 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ex implementatio
37090 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 53  ns provided by S
370a0 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66  QLite are.** suf
370b0 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72  ficient, however
370c0 20 74 68 65 20 75 73 65 72 20 68 61 73 20 74 68   the user has th
370d0 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73  e option of subs
370e0 74 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f  tituting a custo
370f0 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  m.** implementat
37100 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69  ion for speciali
37110 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20  zed deployments 
37120 6f 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77  or systems for w
37130 68 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64  hich SQLite.** d
37140 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20  oes not provide 
37150 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
37160 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68  mentation. In th
37170 69 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 65  is case, the use
37180 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64  r.** creates and
37190 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e   populates an in
371a0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
371b0 74 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 73  tructure to pass
371c0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
371d0 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69  onfig() along wi
371e0 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  th the [SQLITE_C
371f0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74  ONFIG_MUTEX] opt
37200 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  ion..** Addition
37210 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63  ally, an instanc
37220 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  e of this struct
37230 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
37240 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20  as an.** output 
37250 76 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75  variable when qu
37260 65 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 65  erying the syste
37270 6d 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  m for the curren
37280 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  t mutex.** imple
37290 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67  mentation, using
372a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
372b0 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70  FIG_GETMUTEX] op
372c0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
372d0 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68   xMutexInit meth
372e0 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68  od defined by th
372f0 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  is structure is 
37300 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61  invoked as.** pa
37310 72 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69  rt of system ini
37320 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74  tialization by t
37330 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
37340 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
37350 2e 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78  ..** ^The xMutex
37360 49 6e 69 74 20 72 6f 75 74 69 6e 65 20 69 73 20  Init routine is 
37370 63 61 6c 6c 65 20 62 79 20 53 51 4c 69 74 65 20  calle by SQLite 
37380 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72  exactly once for
37390 20 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69   each.** effecti
373a0 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ve call to [sqli
373b0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
373c0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d  ]..**.** ^The xM
373d0 75 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64  utexEnd method d
373e0 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73  efined by this s
373f0 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f  tructure is invo
37400 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ked as.** part o
37410 66 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77  f system shutdow
37420 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  n by the sqlite3
37430 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63  _shutdown() func
37440 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70  tion. The.** imp
37450 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
37460 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78  his method is ex
37470 70 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73  pected to releas
37480 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e  e all outstandin
37490 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f  g.** resources o
374a0 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d  btained by the m
374b0 75 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70  utex methods imp
374c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70  lementation, esp
374d0 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65  ecially.** those
374e0 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65   obtained by the
374f0 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68   xMutexInit meth
37500 6f 64 2e 20 20 5e 54 68 65 20 78 4d 75 74 65 78  od.  ^The xMutex
37510 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  End().** interfa
37520 63 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 65 78  ce is invoked ex
37530 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65  actly once for e
37540 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
37550 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
37560 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65  ..**.** ^(The re
37570 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65  maining seven me
37580 74 68 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79  thods defined by
37590 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
375a0 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a  (xMutexAlloc,.**
375b0 20 78 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75   xMutexFree, xMu
375c0 74 65 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78  texEnter, xMutex
375d0 54 72 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65  Try, xMutexLeave
375e0 2c 20 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64  , xMutexHeld and
375f0 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c  .** xMutexNothel
37600 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  d) implement the
37610 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72   following inter
37620 66 61 63 65 73 20 28 72 65 73 70 65 63 74 69 76  faces (respectiv
37630 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ely):.**.** <ul>
37640 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
37650 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
37660 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
37670 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
37680 74 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69  tex_free()] </li
37690 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
376a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
376b0 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  r()] </li>.**   
376c0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
376d0 75 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69  utex_try()] </li
376e0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
376f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
37700 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  e()] </li>.**   
37710 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
37720 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c  utex_held()] </l
37730 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
37740 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
37750 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  held()] </li>.**
37760 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
37770 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
37780 63 65 20 69 73 20 74 68 61 74 20 74 68 65 20 70  ce is that the p
37790 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58  ublic sqlite3_XX
377a0 58 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d  X functions enum
377b0 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20  erated.** above 
377c0 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
377d0 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  any invocations 
377e0 74 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c  that pass a NULL
377f0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
37800 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d  .** of a valid m
37810 75 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65  utex handle. The
37820 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
37830 20 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20   of the methods 
37840 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  defined.** by th
37850 69 73 20 73 74 72 75 63 74 75 72 65 20 61 72 65  is structure are
37860 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f   not required to
37870 20 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73   handle this cas
37880 65 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a  e, the results.*
37890 2a 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e  * of passing a N
378a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  ULL pointer inst
378b0 65 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d  ead of a valid m
378c0 75 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20  utex handle are 
378d0 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e  undefined.** (i.
378e0 65 2e 20 69 74 20 69 73 20 61 63 63 65 70 74 61  e. it is accepta
378f0 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61  ble to provide a
37900 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
37910 20 74 68 61 74 20 73 65 67 66 61 75 6c 74 73 20   that segfaults 
37920 69 66 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73  if.** it is pass
37930 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ed a NULL pointe
37940 72 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  r)..**.** The xM
37950 75 74 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f  utexInit() metho
37960 64 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  d must be thread
37970 73 61 66 65 2e 20 20 5e 49 74 20 6d 75 73 74 20  safe.  ^It must 
37980 62 65 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a  be harmless to.*
37990 2a 20 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49  * invoke xMutexI
379a0 6e 69 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69  nit() mutiple ti
379b0 6d 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  mes within the s
379c0 61 6d 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20  ame process and 
379d0 77 69 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72  without.** inter
379e0 76 65 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20  vening calls to 
379f0 78 4d 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65  xMutexEnd().  Se
37a00 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
37a10 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
37a20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73  xMutexInit() mus
37a30 74 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  t be no-ops..**.
37a40 2a 2a 20 5e 78 4d 75 74 65 78 49 6e 69 74 28 29  ** ^xMutexInit()
37a50 20 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51   must not use SQ
37a60 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  Lite memory allo
37a70 63 61 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33  cation ([sqlite3
37a80 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e  _malloc()].** an
37a90 64 20 69 74 73 20 61 73 73 6f 63 69 61 74 65 73  d its associates
37aa0 29 2e 20 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20  ).  ^Similarly, 
37ab0 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75  xMutexAlloc() mu
37ac0 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74  st not use SQLit
37ad0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
37ae0 63 61 74 69 6f 6e 20 66 6f 72 20 61 20 73 74 61  cation for a sta
37af0 74 69 63 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77  tic mutex.  ^How
37b00 65 76 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63  ever xMutexAlloc
37b10 28 29 20 6d 61 79 20 75 73 65 20 53 51 4c 69 74  () may use SQLit
37b20 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
37b30 63 61 74 69 6f 6e 20 66 6f 72 20 61 20 66 61 73  cation for a fas
37b40 74 20 6f 72 20 72 65 63 75 72 73 69 76 65 20 6d  t or recursive m
37b50 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  utex..**.** ^SQL
37b60 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
37b70 74 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 20  the xMutexEnd() 
37b80 6d 65 74 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c  method when [sql
37b90 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
37ba0 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62   is.** called, b
37bb0 75 74 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  ut only if the p
37bc0 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75  rior call to xMu
37bd0 74 65 78 49 6e 69 74 20 72 65 74 75 72 6e 65 64  texInit returned
37be0 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49   SQLITE_OK..** I
37bf0 66 20 78 4d 75 74 65 78 49 6e 69 74 20 66 61 69  f xMutexInit fai
37c00 6c 73 20 69 6e 20 61 6e 79 20 77 61 79 2c 20 69  ls in any way, i
37c10 74 20 69 73 20 65 78 70 65 63 74 65 64 20 74 6f  t is expected to
37c20 20 63 6c 65 61 6e 20 75 70 20 61 66 74 65 72 20   clean up after 
37c30 69 74 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20  itself.** prior 
37c40 74 6f 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f  to returning..*/
37c50 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
37c60 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
37c70 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75  thods sqlite3_mu
37c80 74 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  tex_methods;.str
37c90 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
37ca0 78 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  x_methods {.  in
37cb0 74 20 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28  t (*xMutexInit)(
37cc0 76 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78  void);.  int (*x
37cd0 4d 75 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b  MutexEnd)(void);
37ce0 0a 20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  .  sqlite3_mutex
37cf0 20 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29   *(*xMutexAlloc)
37d00 28 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a  (int);.  void (*
37d10 78 4d 75 74 65 78 46 72 65 65 29 28 73 71 6c 69  xMutexFree)(sqli
37d20 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
37d30 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74  void (*xMutexEnt
37d40 65 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  er)(sqlite3_mute
37d50 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  x *);.  int (*xM
37d60 75 74 65 78 54 72 79 29 28 73 71 6c 69 74 65 33  utexTry)(sqlite3
37d70 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69  _mutex *);.  voi
37d80 64 20 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29  d (*xMutexLeave)
37d90 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
37da0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
37db0 78 48 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d  xHeld)(sqlite3_m
37dc0 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28  utex *);.  int (
37dd0 2a 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28  *xMutexNotheld)(
37de0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
37df0 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ;.};../*.** CAPI
37e00 33 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69  3REF: Mutex Veri
37e10 66 69 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  fication Routine
37e20 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  s.**.** The sqli
37e30 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
37e40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
37e50 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75  ex_notheld() rou
37e60 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74  tines.** are int
37e70 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
37e80 73 69 64 65 20 61 73 73 65 72 74 28 29 20 73 74  side assert() st
37e90 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20  atements.  ^The 
37ea0 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e  SQLite core.** n
37eb0 65 76 65 72 20 75 73 65 73 20 74 68 65 73 65 20  ever uses these 
37ec0 72 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74 20  routines except 
37ed0 69 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72 74  inside an assert
37ee0 28 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69  () and applicati
37ef0 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73  ons.** are advis
37f00 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65  ed to follow the
37f10 20 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72   lead of the cor
37f20 65 2e 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20  e.  ^The SQLite 
37f30 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f  core only.** pro
37f40 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61  vides implementa
37f50 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20  tions for these 
37f60 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74  routines when it
37f70 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20   is compiled.** 
37f80 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
37f90 44 45 42 55 47 20 66 6c 61 67 2e 20 20 5e 45 78  DEBUG flag.  ^Ex
37fa0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70  ternal mutex imp
37fb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20  lementations.** 
37fc0 61 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65  are only require
37fd0 64 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65  d to provide the
37fe0 73 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53  se routines if S
37ff0 51 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a  QLITE_DEBUG is.*
38000 2a 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66  * defined and if
38010 20 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64   NDEBUG is not d
38020 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
38030 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68  hese routines sh
38040 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65  ould return true
38050 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e   if the mutex in
38060 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a   their argument.
38070 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f  ** is held or no
38080 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69  t held, respecti
38090 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c  vely, by the cal
380a0 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a  ling thread..**.
380b0 2a 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ** ^The implemen
380c0 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65  tation is not re
380d0 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64  quired to provid
380e0 65 64 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  ed versions of t
380f0 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  hese.** routines
38100 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77   that actually w
38110 6f 72 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c  ork. If the impl
38120 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20  ementation does 
38130 6e 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b  not provide work
38140 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ing.** versions 
38150 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
38160 73 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20  s, it should at 
38170 6c 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 74  least provide st
38180 75 62 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a  ubs that always.
38190 2a 2a 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  ** return true s
381a0 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20  o that one does 
381b0 6e 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75 73  not get spurious
381c0 20 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75   assertion failu
381d0 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  res..**.** ^If t
381e0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  he argument to s
381f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
38200 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  d() is a NULL po
38210 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68  inter then.** th
38220 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  e routine should
38230 20 72 65 74 75 72 6e 20 31 2e 20 20 20 54 68 69   return 1.   Thi
38240 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d  s seems counter-
38250 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a  intuitive since.
38260 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d  ** clearly the m
38270 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68  utex cannot be h
38280 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e  eld if it does n
38290 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 20 74  ot exist.  But t
382a0 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e  he.** the reason
382b0 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20   the mutex does 
382c0 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 65 63  not exist is bec
382d0 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 20 69  ause the build i
382e0 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d  s not.** using m
382f0 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20  utexes.  And we 
38300 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  do not want the 
38310 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e  assert() contain
38320 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20  ing the.** call 
38330 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
38340 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c  _held() to fail,
38350 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72   so a non-zero r
38360 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20  eturn is.** the 
38370 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e  appropriate thin
38380 67 20 74 6f 20 64 6f 2e 20 20 5e 54 68 65 20 73  g to do.  ^The s
38390 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
383a0 68 65 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66  held().** interf
383b0 61 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20  ace should also 
383c0 72 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69  return 1 when gi
383d0 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ven a NULL point
383e0 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e  er..*/.#ifndef N
383f0 44 45 42 55 47 0a 69 6e 74 20 73 71 6c 69 74 65  DEBUG.int sqlite
38400 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c  3_mutex_held(sql
38410 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e  ite3_mutex*);.in
38420 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
38430 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f  notheld(sqlite3_
38440 6d 75 74 65 78 2a 29 3b 0a 23 65 6e 64 69 66 0a  mutex*);.#endif.
38450 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
38460 20 4d 75 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a   Mutex Types.**.
38470 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
38480 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69  mutex_alloc()] i
38490 6e 74 65 72 66 61 63 65 20 74 61 6b 65 73 20 61  nterface takes a
384a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
384b0 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65  .** which is one
384c0 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
384d0 72 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  r constants..**.
384e0 2a 2a 20 54 68 65 20 73 65 74 20 6f 66 20 73 74  ** The set of st
384f0 61 74 69 63 20 6d 75 74 65 78 65 73 20 6d 61 79  atic mutexes may
38500 20 63 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65   change from one
38510 20 53 51 4c 69 74 65 20 72 65 6c 65 61 73 65 20   SQLite release 
38520 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20  to the.** next. 
38530 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
38540 61 74 20 6f 76 65 72 72 69 64 65 20 74 68 65 20  at override the 
38550 62 75 69 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c  built-in mutex l
38560 6f 67 69 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20  ogic must be.** 
38570 70 72 65 70 61 72 65 64 20 74 6f 20 61 63 63 6f  prepared to acco
38580 6d 6d 6f 64 61 74 65 20 61 64 64 69 74 69 6f 6e  mmodate addition
38590 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  al static mutexe
385a0 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
385b0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
385c0 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
385d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
385e0 45 58 5f 52 45 43 55 52 53 49 56 45 20 20 20 20  EX_RECURSIVE    
385f0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
38600 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
38610 43 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64  C_MASTER    2.#d
38620 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
38630 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20  EX_STATIC_MEM   
38640 20 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65      3  /* sqlite
38650 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64  3_malloc() */.#d
38660 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
38670 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20  EX_STATIC_MEM2  
38680 20 20 20 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53      4  /* NOT US
38690 45 44 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ED */.#define SQ
386a0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
386b0 43 5f 4f 50 45 4e 20 20 20 20 20 20 34 20 20 2f  C_OPEN      4  /
386c0 2a 20 73 71 6c 69 74 65 33 42 74 72 65 65 4f 70  * sqlite3BtreeOp
386d0 65 6e 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  en() */.#define 
386e0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
386f0 54 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20  TIC_PRNG      5 
38700 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64   /* sqlite3_rand
38710 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  om() */.#define 
38720 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
38730 54 49 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20  TIC_LRU       6 
38740 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73   /* lru page lis
38750 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
38760 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
38770 5f 4c 52 55 32 20 20 20 20 20 20 37 20 20 2f 2a  _LRU2      7  /*
38780 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a   lru page list *
38790 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
387a0 46 3a 20 52 65 74 72 69 65 76 65 20 74 68 65 20  F: Retrieve the 
387b0 6d 75 74 65 78 20 66 6f 72 20 61 20 64 61 74 61  mutex for a data
387c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
387d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
387e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
387f0 70 6f 69 6e 74 65 72 20 74 68 65 20 5b 73 71 6c  pointer the [sql
38800 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
38810 63 74 20 74 68 61 74 20 0a 2a 2a 20 73 65 72 69  ct that .** seri
38820 61 6c 69 7a 65 73 20 61 63 63 65 73 73 20 74 6f  alizes access to
38830 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
38840 6f 6e 6e 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e  onnection] given
38850 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74   in the argument
38860 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 5b 74 68  .** when the [th
38870 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
38880 20 53 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   Serialized..** 
38890 5e 49 66 20 74 68 65 20 5b 74 68 72 65 61 64 69  ^If the [threadi
388a0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67  ng mode] is Sing
388b0 6c 65 2d 74 68 72 65 61 64 20 6f 72 20 4d 75 6c  le-thread or Mul
388c0 74 69 2d 74 68 72 65 61 64 20 74 68 65 6e 20 74  ti-thread then t
388d0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  his.** routine r
388e0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
388f0 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65  inter..*/.sqlite
38900 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33  3_mutex *sqlite3
38910 5f 64 62 5f 6d 75 74 65 78 28 73 71 6c 69 74 65  _db_mutex(sqlite
38920 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 5