System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 4f57118a044d8c52de05942ee6f025a8942d41dd:


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 23 69 66 6e 64 65 66 20 53 51  ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0dc0: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0dd0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0de0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0df0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0e00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0e10: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0e20: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e40: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e50: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e60: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e70: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e80: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e90: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0ea0: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0eb0: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0ec0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ed0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0ee0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ef0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0f00: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0f10: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0f20: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f30: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f40: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f50: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f60: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f70: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f80: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f90: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0fb0: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0fc0: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fd0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fe0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0ff0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1010: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33  ERSION        "3
1020: 2e 37 2e 39 22 0a 23 64 65 66 69 6e 65 20 53 51  .7.9".#define SQ
1030: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1040: 42 45 52 20 33 30 30 37 30 30 39 0a 23 64 65 66  BER 3007009.#def
1050: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1060: 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 31 2d  E_ID      "2011-
1070: 31 31 2d 30 38 20 31 35 3a 30 36 3a 30 35 20 61  11-08 15:06:05 a
1080: 34 39 39 61 65 33 38 33 35 65 64 37 66 31 35 39  499ae3835ed7f159
1090: 31 63 34 30 62 65 61 32 30 65 30 63 39 37 66 35  1c40bea20e0c97f5
10a0: 38 63 65 65 64 62 62 22 0a 0a 2f 2a 0a 2a 2a 20  8ceedbb"../*.** 
10b0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
10c0: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
10d0: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45  on Numbers.** KE
10e0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
10f0: 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33  version, sqlite3
1100: 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20  _sourceid.**.** 
1110: 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  These interfaces
1120: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d   provide the sam
1130: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  e information as
1140: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52   the [SQLITE_VER
1150: 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  SION],.** [SQLIT
1160: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1170: 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53  ], and [SQLITE_S
1180: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
1190: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a  rocessor macros.
11a0: 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63  ** but are assoc
11b0: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c  iated with the l
11c0: 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f  ibrary instead o
11d0: 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  f the header fil
11e0: 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a  e.  ^(Cautious.*
11f0: 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  * programmers mi
1200: 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65  ght include asse
1210: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20  rt() statements 
1220: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
1230: 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66  tion to.** verif
1240: 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65  y that values re
1250: 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1260: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68  interfaces match
1270: 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a   the macros in.*
1280: 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e  * the header, an
1290: 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68  d thus insure th
12a0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
12b0: 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  on is.** compile
12c0: 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20  d with matching 
12d0: 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64  library and head
12e0: 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  er files..**.** 
12f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1300: 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c  >.** assert( sql
1310: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1320: 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45  number()==SQLITE
1330: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
1340: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1350: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75  rcmp(sqlite3_sou
1360: 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53  rceid(),SQLITE_S
1370: 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a  OURCE_ID)==0 );.
1380: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
1390: 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  p(sqlite3_libver
13a0: 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45  sion(),SQLITE_VE
13b0: 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20  RSION)==0 );.** 
13c0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13d0: 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
13e0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
13f0: 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  [] string consta
1400: 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  nt contains the 
1410: 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f  text of [SQLITE_
1420: 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72  VERSION].** macr
1430: 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  o.  ^The sqlite3
1440: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75  _libversion() fu
1450: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1460: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
1470: 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  ** to the sqlite
1480: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
1490: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
14a0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
14b0: 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69  sion().** functi
14c0: 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  on is provided f
14d0: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73  or use in DLLs s
14e0: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75  ince DLL users u
14f0: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61  sually do not ha
1500: 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63  ve.** direct acc
1510: 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f  ess to string co
1520: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74  nstants within t
1530: 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a  he DLL.  ^The.**
1540: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1550: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e  ion_number() fun
1560: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e  ction returns an
1570: 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74   integer equal t
1580: 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  o.** [SQLITE_VER
1590: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e  SION_NUMBER].  ^
15a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  The sqlite3_sour
15b0: 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  ceid() function 
15c0: 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f  returns .** a po
15d0: 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e  inter to a strin
15e0: 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65  g constant whose
15f0: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61   value is the sa
1600: 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53  me as the .** [S
1610: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d  QLITE_SOURCE_ID]
1620: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1630: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  macro..**.** See
1640: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76   also: [sqlite_v
1650: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1660: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1670: 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1680: 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  I SQLITE_EXTERN 
1690: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
16a0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51  e3_version[];.SQ
16b0: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
16c0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
16d0: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53  version(void);.S
16e0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16f0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1700: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51  urceid(void);.SQ
1710: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1720: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1730: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1740: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1750: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1760: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69  Compilation Opti
1770: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a  ons Diagnostics.
1780: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1790: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
17a0: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e  _used() function
17b0: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20   returns 0 or 1 
17c0: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77  .** indicating w
17d0: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69  hether the speci
17e0: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20  fied option was 
17f0: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63  defined at .** c
1800: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54  ompile time.  ^T
1810: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69  he SQLITE_ prefi
1820: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  x may be omitted
1830: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70   from the .** op
1840: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64  tion name passed
1850: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
1860: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1870: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .  .**.** ^The s
1880: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1890: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74  tion_get() funct
18a0: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61  ion allows itera
18b0: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65  ting.** over the
18c0: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73   list of options
18d0: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e   that were defin
18e0: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  ed at compile ti
18f0: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69  me by.** returni
1900: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70  ng the N-th comp
1910: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile time option 
1920: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69  string.  ^If N i
1930: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a  s out of range,.
1940: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
1950: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72  leoption_get() r
1960: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1970: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c  inter.  ^The SQL
1980: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20  ITE_ .** prefix 
1990: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
19a0: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75  any strings retu
19b0: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  rned by .** sqli
19c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19d0: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  n_get()..**.** ^
19e0: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20  Support for the 
19f0: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74  diagnostic funct
1a00: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ions sqlite3_com
1a10: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a20: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ).** and sqlite3
1a30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a40: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74  et() may be omit
1a50: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e  ted by specifyin
1a60: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  g the .** [SQLIT
1a70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1a80: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69  TION_DIAGS] opti
1a90: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  on at compile ti
1aa0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  me..**.** See al
1ab0: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  so: SQL function
1ac0: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  s [sqlite_compil
1ad0: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20  eoption_used()] 
1ae0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63  and.** [sqlite_c
1af0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b00: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d  ()] and the [com
1b10: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61  pile_options pra
1b20: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  gma]..*/.#ifndef
1b30: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
1b40: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
1b50: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1b60: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1b70: 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74  ption_used(const
1b80: 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29   char *zOptName)
1b90: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
1ba0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1bb0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1bc0: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
1bd0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1be0: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
1bf0: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
1c00: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
1c10: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1c20: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
1c30: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
1c40: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
1c50: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
1c60: 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69 6e 67  ompiled mutexing
1c70: 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 75   code omitted du
1c80: 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  e to the.** [SQL
1c90: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1ca0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
1cb0: 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74 6f  ion being set to
1cc0: 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65   0..**.** SQLite
1cd0: 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64   can be compiled
1ce0: 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74   with or without
1cf0: 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a   mutexes.  When.
1d00: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
1d10: 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 65  HREADSAFE] C pre
1d20: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
1d30: 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78  is 1 or 2, mutex
1d40: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
1d50: 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20  d and SQLite is 
1d60: 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 65  threadsafe.  Whe
1d70: 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  n the.** [SQLITE
1d80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
1d90: 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65  ro is 0, .** the
1da0: 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69   mutexes are omi
1db0: 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74  tted.  Without t
1dc0: 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69  he mutexes, it i
1dd0: 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f  s not safe.** to
1de0: 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63   use SQLite conc
1df0: 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f  urrently from mo
1e00: 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65  re than one thre
1e10: 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69  ad..**.** Enabli
1e20: 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72  ng mutexes incur
1e30: 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70  s a measurable p
1e40: 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c  erformance penal
1e50: 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65  ty..** So if spe
1e60: 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20  ed is of utmost 
1e70: 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d  importance, it m
1e80: 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69  akes sense to di
1e90: 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74  sable.** the mut
1ea0: 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d  exes.  But for m
1eb0: 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d  aximum safety, m
1ec0: 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65  utexes should be
1ed0: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68   enabled..** ^Th
1ee0: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
1ef0: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65  or is for mutexe
1f00: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e  s to be enabled.
1f10: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f20: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1f30: 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74  d by an applicat
1f40: 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ion to make sure
1f50: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72   that the.** ver
1f60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74  sion of SQLite t
1f70: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e  hat it is linkin
1f80: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f  g against was co
1f90: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
1fa0: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69  he desired setti
1fb0: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ng of the [SQLIT
1fc0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fd0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cro..**.** This 
1fe0: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
1ff0: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f  eports on the co
2000: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78  mpile-time mutex
2010: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74   setting.** of t
2020: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
2030: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66  DSAFE] flag.  If
2040: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
2050: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49  led with.** SQLI
2060: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20  TE_THREADSAFE=1 
2070: 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 78  or =2 then mutex
2080: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  es are enabled b
2090: 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a  y default but.**
20a0: 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72   can be fully or
20b0: 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62   partially disab
20c0: 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c  led using a call
20d0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
20e0: 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74  fig()].** with t
20f0: 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45  he verbs [SQLITE
2100: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
2110: 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  READ], [SQLITE_C
2120: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
2130: 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  D],.** or [SQLIT
2140: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e  E_CONFIG_MUTEX].
2150: 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76    ^(The return v
2160: 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73  alue of the.** s
2170: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2180: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  e() function sho
2190: 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70  ws only the comp
21a0: 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67  ile-time setting
21b0: 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61   of.** thread sa
21c0: 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75  fety, not any ru
21d0: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74  n-time changes t
21e0: 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d  o that setting m
21f0: 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65  ade by.** sqlite
2200: 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f  3_config(). In o
2210: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
2220: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
2230: 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  m sqlite3_thread
2240: 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63  safe().** is unc
2250: 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20  hanged by calls 
2260: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
2270: 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  g().)^.**.** See
2280: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
2290: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74  mode] documentat
22a0: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
22b0: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
22c0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
22d0: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
22e0: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
22f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
2300: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2310: 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f   Handle.** KEYWO
2320: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63  RDS: {database c
2330: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61  onnection} {data
2340: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2350: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  }.**.** Each ope
2360: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
2370: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
2380: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   by a pointer to
2390: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a   an instance of.
23a0: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74  ** the opaque st
23b0: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
23c0: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
23d0: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
23e0: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
23f0: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
2400: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
2410: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
2420: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2430: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2440: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
2450: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
2460: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e  constructors, an
2470: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2480: 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65  ()].** is its de
2490: 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65  structor.  There
24a0: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20   are many other 
24b0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
24c0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
24d0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
24e0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
24f0: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
2500: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
2510: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
2520: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2530: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2540: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2550: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2560: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2570: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2580: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
2590: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
25a0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
25b0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
25c0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
25d0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
25e0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
25f0: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
2600: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
2610: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
2620: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2630: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2640: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2650: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2660: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2670: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2680: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
2690: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
26a0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
26b0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
26c0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
26d0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
26e0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
26f0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2700: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
2710: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
2720: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2730: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2740: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2750: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2760: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2770: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2780: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
2790: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
27a0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
27b0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
27c0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
27d0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
27e0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
27f0: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2800: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2810: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2820: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2830: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2840: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2850: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2860: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49  ef unsigned SQLI
2870: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f  if defined(_MSC_
28a0: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28  VER) || defined(
28b0: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20  __BORLANDC__).  
28c0: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20  typedef __int64 
28d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
28e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
28f0: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
2900: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20  uint64;.#else.  
2910: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e  typedef long lon
2920: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74  g int sqlite_int
2930: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2940: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67  signed long long
2950: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74   int sqlite_uint
2960: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64  64;.#endif.typed
2970: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  ef sqlite_int64 
2980: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74  sqlite3_int64;.t
2990: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69  ypedef sqlite_ui
29a0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e  nt64 sqlite3_uin
29b0: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63  t64;../*.** If c
29c0: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70  ompiling for a p
29d0: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61  rocessor that la
29e0: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  cks floating poi
29f0: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73  nt support,.** s
2a00: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65  ubstitute intege
2a10: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70  r for floating-p
2a20: 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  oint..*/.#ifdef 
2a30: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
2a40: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66  TING_POINT.# def
2a50: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  ine double sqlit
2a60: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a  e3_int64.#endif.
2a70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a80: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62   Closing A Datab
2a90: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
2aa0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ab0: 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69 6e  3_close() routin
2ac0: 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75 63  e is the destruc
2ad0: 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  tor for the [sql
2ae0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ite3] object..**
2af0: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
2b00: 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75 72  e3_close() retur
2b10: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 74  n SQLITE_OK if t
2b20: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2b30: 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65 73  ect is.** succes
2b40: 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64  sfully destroyed
2b50: 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61   and all associa
2b60: 74 65 64 20 72 65 73 6f 75 72 63 65 73 20 61 72  ted resources ar
2b70: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a  e deallocated..*
2b80: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
2b90: 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65 33 5f  s must [sqlite3_
2ba0: 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
2bb0: 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72  ize] all [prepar
2bc0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a  ed statements].*
2bd0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  * and [sqlite3_b
2be0: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73  lob_close | clos
2bf0: 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e  e] all [BLOB han
2c00: 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65 64  dles] associated
2c10: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73 71   with.** the [sq
2c20: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2c30: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2c40: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2c50: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2c60: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69  qlite3_close() i
2c70: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
2c80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c90: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
2ca0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
2cb0: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
2cc0: 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c 4f 42  ements] or [BLOB
2cd0: 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65 6e 20   handles], then 
2ce0: 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  it returns.** SQ
2cf0: 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a 2a 2a  LITE_BUSY..**.**
2d00: 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f 63 6c   ^If [sqlite3_cl
2d10: 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ose()] is invoke
2d20: 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61  d while a transa
2d30: 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a  ction is open,.*
2d40: 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  * the transactio
2d50: 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  n is automatical
2d60: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
2d70: 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61  **.** The C para
2d80: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2d90: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 73 74  3_close(C)] must
2da0: 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c   be either a NUL
2db0: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20  L.** pointer or 
2dc0: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
2dd0: 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61  ect pointer obta
2de0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
2df0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2e00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2e10: 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
2e20: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
2e30: 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79  d not previously
2e40: 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c   closed..** ^Cal
2e50: 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f  ling sqlite3_clo
2e60: 73 65 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  se() with a NULL
2e70: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
2e80: 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72 6d 6c  t is a .** harml
2e90: 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51  ess no-op..*/.SQ
2ea0: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2eb0: 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74  ite3_close(sqlit
2ec0: 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  e3 *);../*.** Th
2ed0: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
2ee0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
2ef0: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
2f00: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
2f10: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
2f20: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
2f30: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
2f40: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
2f50: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
2f60: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
2f70: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
2f80: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
2f90: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
2fa0: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
2fb0: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
2fc0: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a   Interface.**.**
2fd0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
2fe0: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
2ff0: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3000: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3010: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3020: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3030: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
3040: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3050: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
3060: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
3070: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
3080: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
3090: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
30a0: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
30b0: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
30c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30d0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
30e0: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
30f0: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3100: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3110: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3120: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3130: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
3140: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
3150: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
3160: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
3170: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
3180: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
3190: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
31a0: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
31b0: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
31c0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
31d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
31e0: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
31f0: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3200: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3210: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3220: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3230: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
3240: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
3250: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3260: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
3270: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
3280: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
3290: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
32a0: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
32b0: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
32c0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
32d0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
32e0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
32f0: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3300: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3310: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3320: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3330: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
3340: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
3350: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
3360: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3370: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3380: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
3390: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
33a0: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
33b0: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
33c0: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
33d0: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
33e0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
33f0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3400: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3410: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3420: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3430: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
3440: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
3450: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
3460: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
3470: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
3480: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3490: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
34a0: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
34b0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
34c0: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
34d0: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
34e0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
34f0: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3500: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3510: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3520: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3530: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
3540: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3550: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
3560: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
3570: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3580: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3590: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
35a0: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
35b0: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
35c0: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
35d0: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
35e0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
35f0: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3600: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3610: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
3620: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3630: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3640: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3650: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3660: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3670: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3680: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3690: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
36a0: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
36b0: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
36c0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
36d0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
36e0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36f0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3700: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3710: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
3720: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
3730: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3740: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3750: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3760: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3770: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3780: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3790: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
37a0: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
37b0: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
37c0: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
37d0: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
37e0: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
37f0: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3800: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3810: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
3820: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
3830: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3840: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3850: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3860: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3870: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3880: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3890: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
38a0: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
38b0: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
38c0: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
38d0: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
38e0: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
38f0: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3900: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3910: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
3920: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
3930: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3940: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3950: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3960: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3970: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3980: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3990: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
39a0: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
39b0: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
39c0: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
39d0: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
39e0: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
39f0: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
3a00: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
3a10: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
3a20: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
3a30: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
3a40: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3a50: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
3a60: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
3a70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3a80: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3a90: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3aa0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3ab0: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3ac0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3ad0: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
3ae0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3af0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3b00: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3b10: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3b20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3b30: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3b40: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3b50: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3b60: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3b70: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3b80: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3b90: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3ba0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3bb0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3bc0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3bd0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3be0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
3bf0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
3c00: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
3c10: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
3c20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3c40: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
3c50: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
3c60: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
3c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c80: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
3c90: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
3ca0: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
3cb0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
3cc0: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
3cd0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
3ce0: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
3cf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3d10: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
3d20: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
3d30: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
3d40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d50: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
3d60: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
3d70: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
3d80: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
3d90: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
3da0: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
3db0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
3dc0: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
3dd0: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
3de0: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
3df0: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
3e00: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
3e10: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
3e20: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
3e30: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
3e40: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
3e50: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73  r to indicates s
3e60: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
3e70: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
3e80: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
3e90: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
3ea0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3eb0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
3ec0: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
3ed0: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
3ee0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c  d result codes],
3ef0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  .** [sqlite3_vta
3f00: 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
3f10: 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
3f20: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
3f30: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
3f40: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3f50: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3f60: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3f70: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
3f80: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
3f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
3fa0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
3fb0: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
3fc0: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
3fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fe0: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
3ff0: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
4000: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
4010: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
4020: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
4030: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
4040: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
4050: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4060: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
4070: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
4080: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
4090: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
40a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
40b0: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
40c0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
40d0: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
40e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40f0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
4100: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
4110: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
4120: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4130: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
4140: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
4150: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
4160: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4170: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
4180: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
4190: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
41a0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
41b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
41c0: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
41d0: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
41e0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
41f0: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
4200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4210: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
4220: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
4230: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
4240: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
4250: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
4260: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
4270: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
4280: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
4290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42a0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
42b0: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
42c0: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
42d0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
42e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
42f0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4300: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4310: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4320: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
4330: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4340: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
4350: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
4360: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
4370: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
4380: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
4390: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
43a0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
43b0: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
43d0: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
43e0: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
43f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4400: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
4410: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
4420: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
4430: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4440: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
4450: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
4460: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
4470: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
4480: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
4490: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
44a0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
44b0: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
44c0: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
44d0: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
44e0: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
44f0: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
4500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4510: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
4520: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
4530: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
4540: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
4550: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
4560: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
4570: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
4580: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
4590: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
45a0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
45b0: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
45c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
45d0: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
45e0: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
45f0: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
4600: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
4610: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
4620: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
4630: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4640: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
4650: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
4660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
4670: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
4680: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
4690: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
46a0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
46b0: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
46c0: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
46d0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
46e0: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
46f0: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4700: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4710: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4720: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4730: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4740: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
4750: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
4760: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
4770: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
4780: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
4790: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
47a0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
47b0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
47c0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
47d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
47e0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
47f0: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4800: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4810: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4820: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4830: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4840: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
4850: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
4860: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
4870: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
4880: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
4890: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
48a0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
48b0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
48c0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
48d0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
48e0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
48f0: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4900: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4910: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4920: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4930: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4940: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4950: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
4960: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
4970: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
4980: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
4990: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
49a0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
49b0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
49c0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
49d0: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
49e0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49f0: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4a00: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4a10: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4a20: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4a30: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4a40: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4a50: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
4a60: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
4a70: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
4a80: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4a90: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
4aa0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
4ab0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
4ac0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
4ad0: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
4ae0: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
4af0: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
4b00: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
4b10: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4b20: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
4b30: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
4b40: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
4b50: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
4b60: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
4b70: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
4b80: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
4b90: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
4ba0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
4bb0: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
4bc0: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
4bd0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
4be0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4bf0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
4c00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4c10: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4c20: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4c30: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
4c40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4c50: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
4c60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4c70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4c80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4c90: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4ca0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4cb0: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
4cc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4cd0: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
4ce0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4cf0: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
4d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d10: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4d20: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4d30: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
4d40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4d50: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
4d60: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4d70: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4d90: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
4da0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4db0: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
4dc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4dd0: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
4de0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4df0: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
4e00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e10: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
4e20: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e30: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
4e40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e50: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
4e60: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e70: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4e80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e90: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4ea0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4eb0: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
4ec0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ed0: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
4ee0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ef0: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
4f00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f10: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
4f20: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
4f30: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
4f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f50: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
4f60: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f70: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
4f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f90: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4fa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fb0: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
4fc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fd0: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
4fe0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ff0: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
5000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5010: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
5020: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5030: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
5040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5050: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
5060: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5070: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
5080: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5090: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
50a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
50b0: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
50c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
50d0: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
50e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
50f0: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
5100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5110: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
5120: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5130: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
5140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5150: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
5160: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
5170: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
5180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5190: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
51a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
51b0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
51c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
51d0: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
51e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
51f0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5210: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5220: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5230: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5240: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5250: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
5260: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
5270: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
5280: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5290: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
52a0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
52b0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
52c0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
52d0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
52e0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
52f0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
5300: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
5310: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5320: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5330: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5340: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5350: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
5360: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
5370: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5380: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
5390: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
53a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53b0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
53c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
53d0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
53e0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
53f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5400: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5410: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5420: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5430: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5450: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5460: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5470: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5480: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5490: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54a0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
54b0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
54c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
54d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54e0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
54f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5500: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5520: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5530: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5540: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5550: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5560: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
5570: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5580: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5590: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
55a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55b0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
55c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
55d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
55e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55f0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5600: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5610: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5620: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5630: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5640: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5650: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5670: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5680: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5690: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
56a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56b0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
56c0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
56d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
56e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56f0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5700: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5710: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5730: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5740: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
5750: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5770: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
5780: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
5790: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
57a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
57b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57c0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
57d0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
57e0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
57f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5810: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
5820: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
5830: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5840: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5860: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
5870: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
5880: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5890: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
58a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58b0: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
58c0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
58d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
58e0: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
58f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5900: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
5910: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
5920: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5930: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
5940: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
5950: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
5960: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
5970: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5980: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
5990: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
59a0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
59b0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
59c0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
59d0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
59e0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
59f0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5a00: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5a10: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5a20: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5a30: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5a40: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
5a50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5a60: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
5a70: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
5a80: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
5a90: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
5aa0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5ab0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
5ac0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
5ad0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
5ae0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
5af0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
5b00: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
5b10: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
5b20: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
5b30: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
5b40: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
5b50: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5b60: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
5b70: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
5b80: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
5b90: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
5ba0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
5bb0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
5bc0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
5bd0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
5be0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
5bf0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
5c00: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
5c10: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5c20: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
5c30: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
5c40: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
5c50: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
5c60: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
5c70: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
5c80: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  e()..*/.#define 
5c90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5ca0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
5cb0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
5cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5cd0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
5ce0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5cf0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5d00: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5d10: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
5d20: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
5d30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5d40: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
5d50: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5d60: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
5d70: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
5d80: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
5d90: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5da0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5db0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5dc0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5dd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5de0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
5df0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5e00: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
5e10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5e20: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
5e30: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5e50: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
5e60: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5e70: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
5e80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5e90: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
5ea0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
5eb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5ec0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
5ed0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ee0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
5ef0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
5f00: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
5f10: 20 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a   0x00000800../*.
5f20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
5f30: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
5f40: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
5f50: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
5f60: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
5f70: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
5f80: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
5f90: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
5fa0: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
5fb0: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
5fc0: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
5fd0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
5fe0: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
5ff0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
6000: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
6010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6020: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
6030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6040: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
6050: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
6060: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
6070: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
6080: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
6090: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
60a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
60b0: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
60c0: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
60d0: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
60e0: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
60f0: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
6100: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6110: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
6120: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
6130: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
6140: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6150: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
6160: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
6170: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
6180: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
6190: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
61a0: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
61b0: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
61c0: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
61d0: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
61e0: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
61f0: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
6200: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
6210: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6220: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
6230: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
6240: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
6250: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
6260: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
6270: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
6280: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
6290: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
62a0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
62b0: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
62c0: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
62d0: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
62e0: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
62f0: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
6300: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
6310: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6320: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6330: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
6340: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
6350: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
6360: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
6370: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
6380: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
6390: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
63a0: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
63b0: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
63c0: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
63d0: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
63e0: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
63f0: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
6400: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
6410: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
6420: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
6430: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
6440: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
6450: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
6460: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
6470: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
6480: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
6490: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
64a0: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
64b0: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
64c0: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
64d0: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
64e0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
64f0: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
6500: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
6510: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
6520: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6530: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6540: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
6550: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
6560: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
6570: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
6580: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
6590: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
65a0: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
65b0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
65c0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
65d0: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
65e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
65f0: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
6600: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
6610: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6620: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
6630: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
6640: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
6650: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
6660: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
6670: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
6680: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
6690: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
66a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
66b0: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
66c0: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
66d0: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
66e0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
66f0: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
6700: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
6710: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
6720: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
6730: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
6740: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
6750: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
6760: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
6770: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6780: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6790: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
67a0: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
67b0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
67c0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
67d0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
67e0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
67f0: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
6800: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
6810: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
6820: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
6830: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
6840: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
6850: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
6860: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
6870: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6880: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
6890: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
68a0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
68b0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
68c0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
68d0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
68e0: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
68f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
6900: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
6910: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
6920: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
6930: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6940: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
6950: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
6960: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
6970: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
6980: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
6990: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
69a0: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
69b0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
69c0: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
69d0: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
69e0: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
69f0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
6a00: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
6a10: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6a20: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
6a30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
6a40: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
6a50: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
6a60: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
6a70: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
6a80: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
6a90: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
6aa0: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
6ab0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
6ac0: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
6ad0: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6ae0: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6af0: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6b00: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6b10: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
6b20: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
6b30: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
6b40: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
6b50: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
6b60: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
6b70: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
6b80: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
6b90: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
6ba0: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
6bb0: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
6bc0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
6bd0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
6be0: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
6bf0: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
6c00: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
6c10: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
6c20: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
6c30: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
6c40: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
6c50: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
6c60: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
6c70: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
6c80: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
6c90: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
6ca0: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
6cb0: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
6cc0: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
6cd0: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
6ce0: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
6cf0: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
6d00: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
6d10: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6d20: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
6d30: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6d40: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
6d50: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
6d60: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
6d70: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
6d80: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
6d90: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6da0: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
6db0: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
6dc0: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
6dd0: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
6de0: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
6df0: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
6e00: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
6e10: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
6e20: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
6e30: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
6e40: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
6e50: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
6e60: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
6e70: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
6e80: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
6e90: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
6ea0: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
6eb0: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
6ec0: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
6ed0: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
6ee0: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
6ef0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
6f00: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
6f10: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
6f20: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
6f30: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
6f40: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
6f50: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
6f60: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
6f70: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
6f80: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
6f90: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
6fa0: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
6fb0: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
6fc0: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
6fd0: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
6fe0: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
6ff0: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
7000: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
7010: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
7020: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
7030: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
7040: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
7050: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
7060: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
7070: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
7080: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
7090: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
70a0: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
70b0: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
70c0: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
70d0: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
70e0: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
70f0: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
7100: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
7110: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
7120: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
7130: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
7140: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
7150: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
7160: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
7170: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
7180: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
7190: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
71a0: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43  .** A [SQLITE_FC
71b0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20  NTL_LOCKSTATE | 
71c0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
71d0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
71e0: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
71f0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7200: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7210: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7220: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7230: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7240: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7250: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7260: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
7270: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
7280: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
7290: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
72a0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
72b0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
72c0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
72d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
72e0: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
72f0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
7300: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
7310: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
7320: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
7330: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
7340: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
7350: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
7360: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
7370: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
7380: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
7390: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
73a0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
73b0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
73c0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
73d0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
73e0: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
73f0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
7400: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
7410: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
7420: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7430: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
7440: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7450: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
7460: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7470: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
7480: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7490: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
74a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
74b0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
74c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
74d0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
74e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
74f0: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
7500: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7510: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
7520: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7530: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
7540: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7550: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
7560: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7570: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
7580: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
7590: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
75a0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
75b0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
75c0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
75d0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
75e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
75f0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
7600: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
7610: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
7620: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
7630: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
7640: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
7650: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
7660: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
7670: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
7680: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
7690: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
76a0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
76b0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
76c0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
76d0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
76e0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
76f0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
7700: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
7710: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
7720: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
7730: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
7740: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
7750: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7760: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
7770: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
7780: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
7790: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
77a0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
77b0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
77c0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
77d0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
77e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
77f0: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
7800: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
7810: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
7820: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
7830: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
7840: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
7850: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
7860: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
7870: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
7880: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
7890: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
78a0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
78b0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
78c0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
78d0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
78e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
78f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7900: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
7910: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
7920: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7930: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
7940: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
7950: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7960: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
7970: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7980: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
7990: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
79a0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
79b0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
79c0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
79d0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
79e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
79f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
7a00: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
7a10: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
7a20: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
7a30: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
7a40: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
7a50: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
7a60: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
7a70: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7a80: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
7a90: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
7aa0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
7ab0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
7ac0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
7ad0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
7ae0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
7af0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
7b00: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
7b10: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
7b20: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
7b30: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
7b40: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
7b50: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
7b60: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7b70: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
7b80: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
7b90: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7ba0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
7bb0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
7bc0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
7bd0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
7be0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7bf0: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
7c00: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
7c10: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
7c20: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
7c30: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
7c40: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
7c50: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
7c60: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
7c70: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7c80: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
7c90: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7ca0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
7cb0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7cc0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
7cd0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
7ce0: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
7cf0: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
7d00: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
7d10: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
7d20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
7d30: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
7d40: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a  trol Opcodes.**.
7d50: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
7d60: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f   constants are o
7d70: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78  pcodes for the x
7d80: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7d90: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  od.** of the [sq
7da0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7db0: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72  ] object and for
7dc0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7dd0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a  le_control()].**
7de0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
7df0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
7e00: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f  NTL_LOCKSTATE] o
7e10: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
7e20: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
7e30: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
7e40: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
7e50: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77  trol method to w
7e60: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74  rite the current
7e70: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65   state of.** the
7e80: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53   lock (one of [S
7e90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
7ea0: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  , [SQLITE_LOCK_S
7eb0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  HARED],.** [SQLI
7ec0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7ed0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7ee0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51  PENDING], or [SQ
7ef0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7f00: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e  IVE]).** into an
7f10: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68   integer that th
7f20: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
7f30: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20  points to. This 
7f40: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
7f50: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
7f60: 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  ting and only ne
7f70: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
7f80: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
7f90: 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e  TEST.** is defin
7fa0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ed..**.** The [S
7fb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
7fc0: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
7fd0: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
7fe0: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
7ff0: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
8000: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
8010: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
8020: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
8030: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
8040: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
8050: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
8060: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
8070: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
8080: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
8090: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
80a0: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
80b0: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
80c0: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
80d0: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
80e0: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
80f0: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
8100: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
8110: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
8120: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
8130: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8140: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
8150: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8160: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
8170: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
8180: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
8190: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
81a0: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
81b0: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
81c0: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
81d0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
81e0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
81f0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8200: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
8210: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
8220: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
8230: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
8240: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
8250: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
8260: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
8270: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
8280: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
8290: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
82a0: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
82b0: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
82c0: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
82d0: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
82e0: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
82f0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
8300: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ystems..**.** Th
8310: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8320: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  FILE_POINTER] op
8330: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
8340: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
8350: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
8360: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
8370: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
8380: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
8390: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
83a0: 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b  tion.  See the [
83b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
83c0: 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74  trol()] document
83d0: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64  ation for.** add
83e0: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
83f0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ion..**.** ^(The
8400: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8410: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63  YNC_OMITTED] opc
8420: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
8430: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a   internally by.*
8440: 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e  * SQLite and sen
8450: 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69  t to all VFSes i
8460: 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c  n place of a cal
8470: 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d  l to the xSync m
8480: 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68  ethod.** when th
8490: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
84a0: 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d  ction has [PRAGM
84b0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73  A synchronous] s
84c0: 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20  et to OFF.)^.** 
84d0: 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64  Some specialized
84e0: 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73   VFSes need this
84f0: 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72   signal in order
8500: 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72   to operate corr
8510: 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50  ectly.** when [P
8520: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
8530: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
8540: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73  ronous=OFF] is s
8550: 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a  et, but most .**
8560: 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65   VFSes do not ne
8570: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61  ed this signal a
8580: 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  nd should silent
8590: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
85a0: 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  pcode..** Applic
85b0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
85c0: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
85d0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
85e0: 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63  with this.** opc
85f0: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
8600: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
8610: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
8620: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
8630: 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65  es.** that do re
8640: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
8650: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
8660: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
8670: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
8680: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
8690: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
86a0: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
86b0: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
86c0: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
86d0: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
86e0: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
86f0: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f  ] in order to wo
8700: 72 6b 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  rk to provide ro
8710: 62 75 73 74 6e 65 73 73 20 61 67 61 69 6e 73 74  bustness against
8720: 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70  .** anti-virus p
8730: 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66  rograms.  By def
8740: 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77  ault, the window
8750: 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79  s VFS will retry
8760: 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66   file read,.** f
8770: 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66  ile write, and f
8780: 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61  ile delete opera
8790: 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74  tions up to 10 t
87a0: 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c  imes, with a del
87b0: 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c  ay.** of 25 mill
87c0: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20  iseconds before 
87d0: 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20  the first retry 
87e0: 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c  and with the del
87f0: 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a  ay increasing.**
8800: 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61   by an additiona
8810: 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  l 25 millisecond
8820: 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73  s with each subs
8830: 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54  equent retry.  T
8840: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c  his.** opcode al
8850: 6c 6f 77 73 20 74 68 6f 73 65 20 74 6f 20 76 61  lows those to va
8860: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
8870: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
8880: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
8890: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
88a0: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
88b0: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
88c0: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
88d0: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
88e0: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
88f0: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
8900: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
8910: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
8920: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
8930: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
8940: 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72  eger i the new r
8950: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
8960: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
8970: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
8980: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
8990: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
89a0: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
89b0: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
89c0: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
89d0: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
89e0: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
89f0: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
8a00: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
8a10: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
8a20: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
8a30: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
8a40: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
8a50: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
8a60: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
8a70: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ed..**.** ^The [
8a80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
8a90: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
8aa0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
8ab0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
8ac0: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
8ad0: 7c 20 57 72 69 74 65 20 41 48 65 61 64 20 4c 6f  | Write AHead Lo
8ae0: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
8af0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
8b00: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
8b10: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
8b20: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
8b30: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
8b40: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
8b50: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
8b60: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
8b70: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
8b80: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
8b90: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
8ba0: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
8bb0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
8bc0: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
8bd0: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
8be0: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
8bf0: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
8c00: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
8c10: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
8c20: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
8c30: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
8c40: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
8c50: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
8c60: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
8c70: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
8c80: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
8c90: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
8ca0: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
8cb0: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
8cc0: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
8cd0: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
8ce0: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
8cf0: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
8d00: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
8d10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8d20: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
8d30: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
8d40: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
8d50: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
8d60: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
8d70: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
8d80: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
8d90: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
8da0: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
8db0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
8dc0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
8dd0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
8de0: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
8df0: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
8e00: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
8e10: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
8e20: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
8e30: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  ITE] opcode is i
8e40: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
8e50: 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a   after opening.*
8e60: 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61  * a write transa
8e70: 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74  ction to indicat
8e80: 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69  e that, unless i
8e90: 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t is rolled back
8ea0: 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61   for some.** rea
8eb0: 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20  son, the entire 
8ec0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
8ed0: 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ll be overwritte
8ee0: 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  n by the current
8ef0: 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e   .** transaction
8f00: 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62  . This is used b
8f10: 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69  y VACUUM operati
8f20: 6f 6e 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons..*/.#define 
8f30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
8f40: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31 0a  KSTATE        1.
8f50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
8f60: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
8f70: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
8f80: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
8f90: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33 0a  ROXYFILE      3.
8fa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
8fb0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
8fc0: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
8fd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
8fe0: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 35 0a  E_HINT        5.
8ff0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
9000: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
9010: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
9020: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9030: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 37 0a  E_POINTER     7.
9040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
9050: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
9060: 44 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20  D     8.#define 
9070: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9080: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 39 0a  32_AV_RETRY   9.
9090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
90a0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
90b0: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
90c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
90d0: 52 57 52 49 54 45 20 20 20 20 20 20 20 31 31 0a  RWRITE       11.
90e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
90f0: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
9100: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
9110: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
9120: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
9130: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
9140: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
9150: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
9160: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
9170: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
9180: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
9190: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
91a0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
91b0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
91c0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
91d0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
91e0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
91f0: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
9200: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
9210: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
9220: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
9230: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
9240: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
9250: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
9260: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
9270: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
9280: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
9290: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
92a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
92b0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
92c0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
92d0: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
92e0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
92f0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
9300: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
9310: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
9320: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
9330: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
9340: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
9350: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
9360: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
9370: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
9380: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
9390: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
93a0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
93b0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
93c0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
93d0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
93e0: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
93f0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
9400: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
9410: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
9420: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
9430: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
9440: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
9450: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
9460: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
9470: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
9480: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
9490: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
94a0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
94b0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
94c0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
94d0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
94e0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
94f0: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
9500: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
9510: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
9520: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
9530: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
9540: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
9550: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
9560: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
9570: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
9580: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
9590: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
95a0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
95b0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
95c0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
95d0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
95e0: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
95f0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
9600: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
9610: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
9620: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
9630: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
9640: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
9650: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
9660: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
9670: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
9680: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
9690: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
96a0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
96b0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
96c0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
96d0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
96e0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
96f0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
9700: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
9710: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
9720: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
9730: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
9740: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
9750: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
9760: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
9770: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
9780: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
9790: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
97a0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
97b0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
97c0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
97d0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
97e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
97f0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
9800: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
9810: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
9820: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
9830: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
9840: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
9850: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
9860: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
9870: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
9880: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
9890: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
98a0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
98b0: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
98c0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
98d0: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
98e0: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
98f0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
9900: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
9910: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
9920: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
9930: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
9940: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
9950: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
9960: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
9970: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
9980: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
9990: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
99a0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
99b0: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
99c0: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
99d0: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
99e0: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
99f0: 30 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  0 alphanumeric a
9a00: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
9a10: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
9a20: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
9a30: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
9a40: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
9a50: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
9a60: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
9a70: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
9a80: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
9a90: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
9aa0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
9ab0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
9ac0: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
9ad0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
9ae0: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
9af0: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
9b00: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
9b10: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
9b20: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
9b30: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
9b40: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
9b50: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
9b60: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
9b70: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
9b80: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
9b90: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
9ba0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
9bb0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
9bc0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
9bd0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
9be0: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
9bf0: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
9c00: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
9c10: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
9c20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
9c30: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
9c40: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
9c50: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
9c60: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
9c70: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
9c80: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
9c90: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
9ca0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
9cb0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
9cc0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
9cd0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
9ce0: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
9cf0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
9d00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
9d10: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
9d20: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
9d30: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
9d40: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
9d50: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
9d60: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
9d70: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
9d80: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
9d90: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
9da0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
9db0: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
9dc0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
9dd0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
9de0: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
9df0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
9e00: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
9e10: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
9e20: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
9e30: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
9e40: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
9e50: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
9e60: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
9e70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
9e80: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
9e90: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
9ea0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
9eb0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
9ec0: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
9ed0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
9ee0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
9ef0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
9f00: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
9f10: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
9f20: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
9f30: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
9f40: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
9f50: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
9f60: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
9f70: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
9f80: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
9f90: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
9fa0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
9fb0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
9fc0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
9fd0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
9fe0: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
9ff0: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
a000: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
a010: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
a020: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
a030: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
a040: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
a050: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
a060: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
a070: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
a080: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
a090: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
a0a0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
a0b0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
a0c0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
a0d0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
a0e0: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
a0f0: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
a100: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
a110: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
a120: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
a130: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
a140: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
a150: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
a160: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
a170: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
a180: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
a190: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
a1a0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
a1b0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
a1c0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
a1d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
a1e0: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
a1f0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
a200: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
a210: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
a220: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
a230: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
a240: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
a250: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
a260: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
a270: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
a280: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
a290: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
a2a0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
a2b0: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
a2c0: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
a2d0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
a2e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
a2f0: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
a300: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
a310: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
a320: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
a330: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
a340: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
a350: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
a360: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
a370: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
a380: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
a390: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
a3a0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
a3b0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
a3c0: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
a3d0: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
a3e0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
a3f0: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
a400: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
a410: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
a420: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
a430: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
a440: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
a450: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
a460: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
a470: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
a480: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
a490: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
a4a0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
a4b0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
a4c0: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
a4d0: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
a4e0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
a4f0: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
a500: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
a510: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
a520: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
a530: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
a540: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
a550: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
a560: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
a570: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
a580: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
a590: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
a5a0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
a5b0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
a5c0: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
a5d0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
a5e0: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
a5f0: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
a600: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
a610: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
a620: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
a630: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
a640: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
a650: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
a660: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
a670: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
a680: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
a690: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
a6a0: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
a6b0: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
a6c0: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
a6d0: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
a6e0: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
a6f0: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
a700: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
a710: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
a720: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
a730: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
a740: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
a750: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
a760: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
a770: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
a780: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
a790: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
a7a0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
a7b0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
a7c0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
a7d0: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
a7e0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
a7f0: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
a800: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
a810: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
a820: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
a830: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
a840: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
a850: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
a860: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
a870: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
a880: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
a890: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
a8a0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
a8b0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
a8c0: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
a8d0: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
a8e0: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
a8f0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
a900: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
a910: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
a920: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
a930: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
a940: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
a950: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
a960: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
a970: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
a980: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
a990: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
a9a0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
a9b0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
a9c0: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
a9d0: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
a9e0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
a9f0: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
aa00: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
aa10: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
aa20: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
aa30: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
aa40: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
aa50: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
aa60: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
aa70: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
aa80: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
aa90: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
aaa0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
aab0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
aac0: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
aad0: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
aae0: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
aaf0: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
ab00: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
ab10: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
ab20: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
ab30: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
ab40: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
ab50: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
ab60: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
ab70: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
ab80: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
ab90: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
aba0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
abb0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
abc0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
abd0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
abe0: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
abf0: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
ac00: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
ac10: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
ac20: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
ac30: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
ac40: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
ac50: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
ac60: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
ac70: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
ac80: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
ac90: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
aca0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
acb0: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
acc0: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
acd0: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
ace0: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
acf0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
ad00: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
ad10: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
ad20: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
ad30: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
ad40: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
ad50: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
ad60: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
ad70: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
ad80: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
ad90: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
ada0: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
adb0: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
adc0: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
add0: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
ade0: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
adf0: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
ae00: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
ae10: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
ae20: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
ae30: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
ae40: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
ae50: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
ae60: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
ae70: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
ae80: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
ae90: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
aea0: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
aeb0: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
aec0: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
aed0: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
aee0: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
aef0: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
af00: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
af10: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
af20: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
af30: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
af40: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
af50: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
af60: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
af70: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
af80: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
af90: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
afa0: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
afb0: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
afc0: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
afd0: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
afe0: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
aff0: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
b000: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
b010: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
b020: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
b030: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
b040: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
b050: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
b060: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
b070: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
b080: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
b090: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
b0a0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
b0b0: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
b0c0: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
b0d0: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
b0e0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
b0f0: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
b100: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
b110: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
b120: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
b130: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
b140: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
b150: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
b160: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
b170: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
b180: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
b190: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
b1a0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
b1b0: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
b1c0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
b1d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
b1e0: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
b1f0: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
b200: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
b210: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
b220: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
b230: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
b240: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
b250: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
b260: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
b270: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
b280: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
b290: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
b2a0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
b2b0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
b2c0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
b2d0: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
b2e0: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
b2f0: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
b300: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
b310: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
b320: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
b330: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
b340: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
b350: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
b360: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
b370: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
b380: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
b390: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
b3a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
b3b0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
b3c0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
b3d0: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
b3e0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
b3f0: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
b400: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
b410: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
b420: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
b430: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
b440: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
b450: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
b460: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
b470: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
b480: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
b490: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
b4a0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
b4b0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
b4c0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
b4d0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
b4e0: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
b4f0: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
b500: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
b510: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
b520: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
b530: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
b540: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
b550: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
b560: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
b570: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
b580: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
b590: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
b5a0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
b5b0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
b5c0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
b5d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
b5e0: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
b5f0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
b600: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
b610: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
b620: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
b630: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
b640: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
b650: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
b660: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
b670: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
b680: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
b690: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
b6a0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
b6b0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
b6c0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
b6d0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
b6e0: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
b6f0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
b700: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
b710: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
b720: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
b730: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
b740: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
b750: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
b760: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
b770: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
b780: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
b790: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
b7a0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
b7b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
b7c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
b7d0: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
b7e0: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
b7f0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
b800: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
b810: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
b820: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
b830: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
b840: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
b850: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
b860: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
b870: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
b880: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
b890: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
b8a0: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
b8b0: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
b8c0: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
b8d0: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
b8e0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
b8f0: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
b900: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
b910: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
b920: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
b930: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
b940: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
b950: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
b960: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
b970: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
b980: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
b990: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
b9a0: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
b9b0: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
b9c0: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
b9d0: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
b9e0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
b9f0: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
ba00: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
ba10: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
ba20: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
ba30: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
ba40: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
ba50: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
ba60: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
ba70: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
ba80: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
ba90: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
baa0: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
bab0: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
bac0: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
bad0: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
bae0: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
baf0: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
bb00: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
bb10: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
bb20: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
bb30: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
bb40: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
bb50: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
bb60: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
bb70: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
bb80: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
bb90: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
bba0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
bbb0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
bbc0: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
bbd0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
bbe0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
bbf0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
bc00: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
bc10: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
bc20: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
bc30: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
bc40: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
bc50: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
bc60: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
bc70: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
bc80: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
bc90: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
bca0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
bcb0: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
bcc0: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
bcd0: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
bce0: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
bcf0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
bd00: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
bd10: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
bd20: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
bd30: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
bd40: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
bd50: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
bd60: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
bd70: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
bd80: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
bd90: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
bda0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
bdb0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
bdc0: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
bdd0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
bde0: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
bdf0: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
be00: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
be10: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
be20: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
be30: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
be40: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
be50: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
be60: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
be70: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
be80: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
be90: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
bea0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
beb0: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
bec0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
bed0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
bee0: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
bef0: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
bf00: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
bf10: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
bf20: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
bf30: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
bf40: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68   was given no th
bf50: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
bf60: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
bf70: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
bf80: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
bf90: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
bfa0: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
bfb0: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
bfc0: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
bfd0: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
bfe0: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
bff0: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
c000: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
c010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
c020: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
c030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
c040: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
c050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c060: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
c070: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
c080: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
c090: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
c0a0: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
c0b0: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
c0c0: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
c0d0: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
c0e0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
c0f0: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
c100: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
c110: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
c120: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
c130: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
c140: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
c150: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
c160: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
c170: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
c180: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
c190: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
c1a0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
c1b0: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
c1c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
c1d0: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
c1e0: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
c1f0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
c200: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
c210: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
c220: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
c230: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
c240: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
c250: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
c260: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
c270: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
c280: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
c290: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
c2a0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
c2b0: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
c2c0: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
c2d0: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
c2e0: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
c2f0: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
c300: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
c310: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
c320: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
c330: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
c340: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
c350: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
c360: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
c370: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
c380: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
c390: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
c3a0: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
c3b0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
c3c0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c3d0: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
c3e0: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
c3f0: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
c400: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
c410: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
c420: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
c430: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
c440: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
c450: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
c460: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
c470: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
c480: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
c490: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c4a0: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
c4b0: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
c4c0: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
c4d0: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
c4e0: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
c4f0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
c500: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
c510: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
c520: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
c530: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
c540: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
c550: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
c560: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c570: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
c580: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
c590: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
c5a0: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
c5b0: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
c5c0: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
c5d0: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
c5e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c5f0: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
c600: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
c610: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
c620: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
c630: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
c640: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
c650: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
c660: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
c670: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
c680: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
c690: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
c6a0: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
c6b0: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
c6c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c6d0: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
c6e0: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
c6f0: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
c700: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
c710: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
c720: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
c730: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
c740: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
c750: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
c760: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c770: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
c780: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
c790: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
c7a0: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
c7b0: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
c7c0: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
c7d0: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
c7e0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c7f0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
c800: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
c810: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
c820: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
c830: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
c840: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
c850: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
c860: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
c870: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
c880: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
c890: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
c8a0: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
c8b0: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
c8c0: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
c8d0: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
c8e0: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
c8f0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
c900: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
c910: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
c920: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
c930: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
c940: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
c950: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
c960: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
c970: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
c980: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
c990: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
c9a0: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
c9b0: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
c9c0: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
c9d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c9e0: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
c9f0: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
ca00: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
ca10: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
ca20: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
ca30: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
ca40: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
ca50: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
ca60: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
ca70: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
ca80: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
ca90: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
caa0: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
cab0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
cac0: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
cad0: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
cae0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
caf0: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
cb00: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
cb10: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
cb20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
cb30: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
cb40: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
cb50: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
cb60: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
cb70: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
cb80: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
cb90: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
cba0: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
cbb0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
cbc0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
cbd0: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
cbe0: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
cbf0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
cc00: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
cc10: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
cc20: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
cc30: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
cc40: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
cc50: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
cc60: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
cc70: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
cc80: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
cc90: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
cca0: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
ccb0: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
ccc0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
ccd0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
cce0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
ccf0: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
cd00: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
cd10: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
cd20: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
cd30: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
cd40: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
cd50: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
cd60: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
cd70: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
cd80: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
cd90: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
cda0: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
cdb0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
cdc0: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
cdd0: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
cde0: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
cdf0: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
ce00: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
ce10: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
ce20: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
ce30: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
ce40: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
ce50: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
ce60: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
ce70: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
ce80: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
ce90: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
cea0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
ceb0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
cec0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
ced0: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
cee0: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
cef0: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
cf00: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
cf10: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
cf20: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
cf30: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
cf40: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
cf50: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
cf60: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
cf70: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
cf80: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
cf90: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
cfa0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
cfb0: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
cfc0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
cfd0: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
cfe0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
cff0: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
d000: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
d010: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
d020: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
d030: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
d040: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
d050: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
d060: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
d070: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
d080: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
d090: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
d0a0: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
d0b0: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
d0c0: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
d0d0: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
d0e0: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
d0f0: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
d100: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
d110: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
d120: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
d130: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
d140: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
d150: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
d160: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
d170: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
d180: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
d190: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
d1a0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
d1b0: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
d1c0: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
d1d0: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
d1e0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
d1f0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
d200: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49  lize(void);.SQLI
d210: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
d220: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
d230: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
d240: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
d250: 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  t(void);.SQLITE_
d260: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
d270: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
d280: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
d290: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
d2a0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
d2b0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d2c0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
d2d0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
d2e0: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
d2f0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
d300: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
d310: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
d320: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
d330: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
d340: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
d350: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
d360: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
d370: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
d380: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
d390: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
d3a0: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
d3b0: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
d3c0: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
d3d0: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
d3e0: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
d3f0: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
d400: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
d410: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
d420: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
d430: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
d440: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
d450: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
d460: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
d470: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
d480: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
d490: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
d4a0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
d4b0: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
d4c0: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
d4d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d4e0: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
d4f0: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
d500: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
d510: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
d520: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
d530: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
d540: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
d550: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
d560: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
d570: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
d580: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
d590: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d5a0: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
d5b0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
d5c0: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
d5d0: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
d5e0: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
d5f0: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
d600: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d610: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
d620: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
d630: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
d640: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
d650: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
d660: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
d670: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
d680: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
d690: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
d6a0: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
d6b0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
d6c0: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
d6d0: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
d6e0: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
d6f0: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
d700: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
d710: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
d720: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
d730: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
d740: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
d750: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
d760: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
d770: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
d780: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
d790: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
d7a0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
d7b0: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
d7c0: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
d7d0: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
d7e0: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
d7f0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
d800: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
d810: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
d820: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
d830: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
d840: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
d850: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
d860: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
d870: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
d880: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
d890: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
d8a0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
d8b0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
d8c0: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
d8d0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
d8e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d8f0: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
d900: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
d910: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
d920: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
d930: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
d940: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
d950: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
d960: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
d970: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
d980: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
d990: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
d9a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
d9b0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
d9c0: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
d9d0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
d9e0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
d9f0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
da00: 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
da10: 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
da20: 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
da30: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
da40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
da50: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
da60: 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
da70: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
da80: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
da90: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
daa0: 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
dab0: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
dac0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
dad0: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
dae0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
daf0: 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
db00: 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
db10: 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
db20: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f   int sqlite3_db_
db30: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
db40: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
db50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
db60: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
db70: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
db80: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
db90: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
dba0: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
dbb0: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
dbc0: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
dbd0: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
dbe0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
dbf0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
dc00: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
dc10: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
dc20: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
dc30: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
dc40: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
dc50: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
dc60: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
dc70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
dc80: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
dc90: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
dca0: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
dcb0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
dcc0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
dcd0: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
dce0: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
dcf0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
dd00: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
dd10: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
dd20: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
dd30: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
dd40: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
dd50: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
dd60: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
dd70: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
dd80: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
dd90: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
dda0: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
ddb0: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
ddc0: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
ddd0: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
dde0: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
ddf0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
de00: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
de10: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
de20: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
de30: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
de40: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
de50: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
de60: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
de70: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
de80: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
de90: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
dea0: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
deb0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
dec0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
ded0: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
dee0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
def0: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
df00: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
df10: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
df20: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
df30: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
df40: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
df50: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
df60: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
df70: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
df80: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
df90: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
dfa0: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
dfb0: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
dfc0: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
dfd0: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
dfe0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
dff0: 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
e000: 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
e010: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
e020: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
e030: 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
e040: 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
e050: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
e060: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
e070: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
e080: 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
e090: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
e0a0: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
e0b0: 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
e0c0: 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
e0d0: 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
e0e0: 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
e0f0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
e100: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
e110: 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
e120: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
e130: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
e140: 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
e150: 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
e160: 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
e170: 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
e180: 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
e190: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
e1a0: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
e1b0: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
e1c0: 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
e1d0: 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
e1e0: 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
e1f0: 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
e200: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e210: 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
e220: 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
e230: 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
e240: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
e250: 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
e260: 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
e270: 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
e280: 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
e290: 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
e2a0: 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
e2b0: 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
e2c0: 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
e2d0: 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
e2e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
e2f0: 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
e300: 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
e310: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
e320: 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
e330: 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
e340: 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
e350: 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
e360: 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
e370: 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
e380: 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
e390: 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
e3a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
e3b0: 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
e3c0: 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
e3d0: 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
e3e0: 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
e3f0: 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
e400: 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
e410: 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
e420: 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
e430: 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
e440: 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
e450: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
e460: 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
e470: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
e480: 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
e490: 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
e4a0: 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
e4b0: 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
e4c0: 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
e4d0: 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
e4e0: 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
e4f0: 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
e500: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
e510: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
e520: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
e530: 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
e540: 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
e550: 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
e560: 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
e570: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
e580: 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
e590: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
e5a0: 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
e5b0: 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
e5c0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
e5d0: 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
e5e0: 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
e5f0: 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
e600: 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
e610: 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
e620: 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
e630: 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
e640: 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
e650: 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
e660: 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
e670: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
e680: 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
e690: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
e6a0: 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
e6b0: 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
e6c0: 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
e6d0: 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
e6e0: 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
e6f0: 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
e700: 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
e710: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
e720: 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
e730: 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
e740: 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
e750: 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
e760: 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
e770: 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
e780: 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
e790: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
e7a0: 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
e7b0: 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
e7c0: 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
e7d0: 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
e7e0: 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
e7f0: 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
e800: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
e810: 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
e820: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
e830: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
e840: 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
e850: 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
e860: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
e870: 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
e880: 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
e890: 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
e8a0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
e8b0: 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
e8c0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
e8d0: 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
e8e0: 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
e8f0: 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
e900: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
e910: 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
e920: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
e930: 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
e940: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
e950: 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
e960: 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
e970: 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
e980: 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
e990: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
e9a0: 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
e9b0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
e9c0: 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
e9d0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
e9e0: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
e9f0: 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
ea00: 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
ea10: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
ea20: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
ea30: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
ea40: 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
ea50: 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
ea60: 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
ea70: 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
ea80: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ea90: 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
eaa0: 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
eab0: 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
eac0: 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
ead0: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
eae0: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
eaf0: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
eb00: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
eb10: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
eb20: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
eb30: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
eb40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
eb50: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
eb60: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
eb70: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
eb80: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
eb90: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
eba0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
ebb0: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
ebc0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
ebd0: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
ebe0: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
ebf0: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
ec00: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
ec10: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
ec20: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
ec30: 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
ec40: 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
ec50: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
ec60: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
ec70: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
ec80: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
ec90: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
eca0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
ecb0: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
ecc0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ecd0: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
ece0: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
ecf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
ed00: 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
ed10: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
ed20: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
ed30: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
ed40: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
ed50: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
ed60: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
ed70: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
ed80: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
ed90: 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
eda0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
edb0: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
edc0: 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
edd0: 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
ede0: 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
edf0: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
ee00: 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
ee10: 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
ee20: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
ee30: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
ee40: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
ee50: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
ee60: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
ee70: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
ee80: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
ee90: 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
eea0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
eeb0: 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
eec0: 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
eed0: 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
eee0: 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
eef0: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
ef00: 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
ef10: 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
ef20: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
ef30: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
ef40: 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
ef50: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
ef60: 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
ef70: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
ef80: 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
ef90: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
efa0: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
efb0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
efc0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
efd0: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
efe0: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
eff0: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
f000: 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
f010: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
f020: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
f030: 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
f040: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f050: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
f060: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
f070: 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
f080: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
f090: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
f0a0: 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
f0b0: 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
f0c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
f0d0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
f0e0: 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
f0f0: 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
f100: 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
f110: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
f120: 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
f130: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
f140: 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
f150: 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
f160: 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
f170: 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
f180: 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
f190: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
f1a0: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
f1b0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
f1c0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
f1d0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
f1e0: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
f1f0: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
f200: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
f210: 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
f220: 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
f230: 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
f240: 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
f250: 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
f260: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
f270: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
f280: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
f290: 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
f2a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
f2b0: 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
f2c0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
f2d0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
f2e0: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
f2f0: 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
f300: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
f310: 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
f320: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
f330: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
f340: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
f350: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
f360: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
f370: 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
f380: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
f390: 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
f3a0: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
f3b0: 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
f3c0: 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
f3d0: 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
f3e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
f3f0: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
f400: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
f410: 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
f420: 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
f430: 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
f440: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
f450: 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
f460: 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
f470: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
f480: 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
f490: 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
f4a0: 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
f4b0: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
f4c0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
f4d0: 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
f4e0: 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
f4f0: 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
f500: 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
f510: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
f520: 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
f530: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
f540: 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
f550: 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
f560: 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
f570: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
f580: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
f590: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
f5a0: 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
f5b0: 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
f5c0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
f5d0: 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
f5e0: 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
f5f0: 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
f600: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
f610: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
f620: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
f630: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
f640: 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
f650: 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
f660: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
f670: 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
f680: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
f690: 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
f6a0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
f6b0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
f6c0: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
f6d0: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
f6e0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
f6f0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
f700: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
f710: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
f720: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
f730: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
f740: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
f750: 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
f760: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
f770: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
f780: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
f790: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
f7a0: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
f7b0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f7c0: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
f7d0: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
f7e0: 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a   ^SQLite makes.*
f7f0: 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  * its own privat
f800: 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  e copy of the co
f810: 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
f820: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
f830: 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  s] structure.** 
f840: 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69  before the [sqli
f850: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  te3_config()] ca
f860: 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e  ll returns.</dd>
f870: 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
f880: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
f890: 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
f8a0: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
f8b0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
f8c0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
f8d0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
f8e0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
f8f0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
f900: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
f910: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
f920: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
f930: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
f940: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
f950: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
f960: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
f970: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
f980: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
f990: 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
f9a0: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
f9b0: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
f9c0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
f9d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
f9e0: 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
f9f0: 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
fa00: 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
fa10: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
fa20: 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
fa30: 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
fa40: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
fa50: 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
fa60: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
fa70: 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
fa80: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
fa90: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
faa0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
fab0: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
fac0: 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e   of type int, in
fad0: 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a  terpreted as a .
fae0: 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63  ** boolean, whic
faf0: 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
fb00: 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
fb10: 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
fb20: 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74  llocation .** st
fb30: 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
fb40: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fb50: 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
fb60: 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  e disabled, the 
fb70: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  .** following SQ
fb80: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
fb90: 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
fba0: 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
fbb0: 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
fbc0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
fbd0: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
fbe0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
fbf0: 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
fc00: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
fc10: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
fc20: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
fc30: 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
fc40: 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
fc50: 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
fc60: 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
fc70: 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
fc80: 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
fc90: 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
fca0: 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
fcb0: 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
fcc0: 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
fcd0: 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
fce0: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
fcf0: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
fd00: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
fd10: 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
fd20: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
fd30: 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
fd40: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
fd50: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
fd60: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
fd70: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
fd80: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
fd90: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
fda0: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
fdb0: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
fdc0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
fdd0: 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
fde0: 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
fdf0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
fe00: 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
fe10: 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
fe20: 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
fe30: 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
fe40: 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
fe50: 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
fe60: 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
fe70: 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
fe80: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
fe90: 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72  ).  The sz.** ar
fea0: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
feb0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e   multiple of 16.
fec0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
fed0: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
fee0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
fef0: 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
ff00: 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
ff10: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
ff20: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
ff30: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f  Lite will use no
ff40: 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73   more than two s
ff50: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
ff60: 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
ff70: 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
ff80: 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65  t to twice the e
ff90: 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
ffa0: 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
ffb0: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  s..** ^SQLite wi
ffc0: 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65  ll never require
ffd0: 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
ffe0: 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
fff0: 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
10000 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
10010 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74   size. ^If SQLit
10020 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
10030 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
10040 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
10050 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
10060 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
10070 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
10080 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
10090 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
100a0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
100b0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
100c0 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  eeded.</dd>.**.*
100d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
100e0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
100f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10100 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
10110 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
10120 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
10130 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
10140 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
10150 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
10160 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
10170 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
10180 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
10190 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
101a0 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
101b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
101c0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
101d0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
101e0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
101f0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
10200 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
10210 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
10220 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70  CONFIG_PCACHE op
10230 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61  tion..** There a
10240 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
10250 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
10260 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  n: A pointer to 
10270 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a  8-byte aligned.*
10280 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
10290 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
102a0 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
102b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
102c0 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
102d0 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
102e0 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
102f0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
10300 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
10310 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
10320 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
10330 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69  32768) plus a li
10340 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65  ttle extra for e
10350 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
10360 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68  er.  ^The page h
10370 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30  eader size is 20
10380 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70   to 40 bytes dep
10390 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65  ending on.** the
103a0 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75   host architectu
103b0 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d  re.  ^It is harm
103c0 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d  less, apart from
103d0 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f   the wasted memo
103e0 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73  ry,.** to make s
103f0 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c  z a little too l
10400 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74  arge.  The first
10410 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
10420 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  uld point to an 
10430 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74  allocation of at
10440 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
10450 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
10460 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
10470 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
10480 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ided by the firs
10490 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61  t argument to sa
104a0 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d  tisfy its.** mem
104b0 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68  ory needs for th
104c0 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20  e first N pages 
104d0 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20  that it adds to 
104e0 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69  cache.  ^If addi
104f0 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
10500 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
10510 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
10520 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
10530 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68   this option, th
10540 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65  en.** SQLite goe
10550 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
10560 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20  lloc()] for the 
10570 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61  additional stora
10580 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65  ge space..** The
10590 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20   pointer in the 
105a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
105b0 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65  ust.** be aligne
105c0 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
105d0 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
105e0 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
105f0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  f SQLite.** will
10600 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   be undefined.</
10610 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
10620 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d  TE_CONFIG_HEAP]]
10630 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10640 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
10650 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
10660 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
10670 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
10680 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  er that SQLite w
10690 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61  ill use.** for a
106a0 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
106b0 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
106c0 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64  ion needs beyond
106d0 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a   those provided.
106e0 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ** for by [SQLIT
106f0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
10700 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f  ] and [SQLITE_CO
10710 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
10720 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
10730 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41  ree arguments: A
10740 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
10750 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
10760 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e  memory,.** the n
10770 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
10780 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
10790 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
107a0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
107b0 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  size..** ^If the
107c0 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
107d0 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
107e0 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
107f0 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
10800 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
10810 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
10820 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
10830 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
10840 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
10850 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
10860 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
10870 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
10880 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20  G_MALLOC].  ^If 
10890 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
108a0 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
108b0 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51  L and either [SQ
108c0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
108d0 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  YS3] or.** [SQLI
108e0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
108f0 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20  5] are defined, 
10900 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61  then the alterna
10910 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tive memory.** a
10920 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61  llocator is enga
10930 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c  ged to handle al
10940 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d  l of SQLites mem
10950 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
10960 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eeds..** The fir
10970 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
10980 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
10990 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
109a0 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
109b0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
109c0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
109d0 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  of SQLite will b
109e0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
109f0 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  The minimum allo
10a00 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63  cation size is c
10a10 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20  apped at 2**12. 
10a20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65  Reasonable value
10a30 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e  s.** for the min
10a40 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
10a50 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68  size are 2**5 th
10a60 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e  rough 2**8.</dd>
10a70 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
10a80 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c  CONFIG_MUTEX]] <
10a90 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10aa0 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
10ab0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
10ac0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
10ad0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
10ae0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
10af0 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
10b00 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
10b10 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
10b20 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
10b30 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
10b40 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
10b50 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
10b60 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
10b70 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
10b80 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
10b90 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
10ba0 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
10bb0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
10bc0 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20   the.** content 
10bd0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
10be0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
10bf0 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
10c00 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
10c10 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10c20 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
10c30 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
10c40 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
10c50 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
10c60 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
10c70 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
10c80 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
10c90 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
10ca0 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
10cb0 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
10cc0 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
10cd0 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
10ce0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10cf0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
10d00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
10d10 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
10d20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
10d30 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
10d40 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
10d50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10d60 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  _GETMUTEX]] <dt>
10d70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
10d80 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
10d90 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
10da0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
10db0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
10dc0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
10dd0 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
10de0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
10df0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
10e00 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
10e10 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
10e20 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
10e30 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
10e40 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
10e50 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
10e60 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
10e70 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
10e80 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
10e90 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
10ea0 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
10eb0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
10ec0 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
10ed0 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
10ee0 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
10ef0 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
10f00 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
10f10 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
10f20 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
10f30 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
10f40 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
10f50 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
10f60 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
10f70 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
10f80 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
10f90 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
10fa0 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
10fb0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
10fc0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
10fd0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10fe0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
10ff0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
11000 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
11010 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
11020 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
11030 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
11040 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11050 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
11060 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11070 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
11080 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
11090 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
110a0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
110b0 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
110c0 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
110d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
110e0 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
110f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11100 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
11110 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11120 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
11130 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
11140 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
11150 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
11160 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
11170 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
11180 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
11190 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
111a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
111b0 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
111c0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
111d0 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
111e0 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
111f0 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
11200 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
11210 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
11220 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
11230 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
11240 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
11250 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
11260 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
11270 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
11280 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
11290 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
112a0 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
112b0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
112c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
112d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
112e0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
112f0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
11300 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
11310 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
11320 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
11330 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
11340 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
11350 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
11360 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
11370 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
11380 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
11390 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
113a0 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
113b0 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
113c0 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
113d0 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
113e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
113f0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 20 3c  IG_GETPCACHE]] <
11400 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11410 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a  _GETPCACHE</dt>.
11420 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
11430 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
11440 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
11450 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
11460 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
11470 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
11480 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  s] object.  SQLi
11490 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65  te copies of the
114a0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65   current.** page
114b0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
114c0 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
114d0 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
114e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
114f0 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
11500 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
11510 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  G</dt>.** <dd> ^
11520 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
11530 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
11540 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
11550 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
11560 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
11570 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
11580 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
11590 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
115a0 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
115b0 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
115c0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
115d0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
115e0 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
115f0 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
11600 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
11610 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
11620 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
11630 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
11640 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
11650 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
11660 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
11670 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
11680 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
11690 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
116a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
116b0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
116c0 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
116d0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
116e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
116f0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
11700 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
11710 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
11720 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
11730 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
11740 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
11750 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
11760 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
11770 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
11780 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
11790 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
117a0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
117b0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
117c0 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
117d0 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
117e0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
117f0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
11800 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
11810 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
11820 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
11830 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
11840 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
11850 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
11860 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
11870 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
11880 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
11890 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
118a0 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
118b0 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
118c0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
118d0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
118e0 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
118f0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
11900 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
11910 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
11920 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
11930 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
11940 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
11950 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
11960 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11970 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
11980 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11990 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68  G_URI.** <dd> Th
119a0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
119b0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
119c0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49  t of type int. I
119d0 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
119e0 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  .** URI handling
119f0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
11a00 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
11a10 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20  ameter is zero, 
11a20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
11a30 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79  g.** is globally
11a40 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52   disabled. If UR
11a50 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
11a60 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20  obally enabled, 
11a70 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a  all filenames.**
11a80 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
11a90 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
11aa0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
11ab0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
11ac0 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
11ad0 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
11ae0 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
11af0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
11b00 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
11b10 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
11b20 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
11b30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
11b40 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
11b50 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
11b60 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
11b70 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73  opened. If it is
11b80 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
11b90 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  ed, filenames ar
11ba0 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70  e.** only interp
11bb0 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66  reted as URIs if
11bc0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
11bd0 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74  _URI flag is set
11be0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   when the.** dat
11bf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11c00 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64   is opened. By d
11c10 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64  efault, URI hand
11c20 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
11c30 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68  .** disabled. Th
11c40 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
11c50 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62  may be changed b
11c60 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  y compiling with
11c70 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
11c80 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20  USE_URI] symbol 
11c90 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 2f 64 6c  defined..** </dl
11ca0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
11cb0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
11cc0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
11cd0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
11ce0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
11cf0 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
11d00 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
11d10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
11d20 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
11d30 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
11d40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
11d50 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
11d60 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
11d70 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
11d80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11d90 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
11da0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
11db0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
11dc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
11dd0 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
11de0 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
11df0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
11e00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
11e10 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
11e20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
11e30 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
11e40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11e50 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
11e60 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
11e70 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
11e80 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
11e90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
11ea0 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
11eb0 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
11ec0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
11ed0 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
11ee0 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
11ef0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
11f00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11f10 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
11f20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
11f30 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
11f40 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
11f50 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
11f60 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
11f70 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
11f80 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
11f90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
11fa0 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
11fb0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
11fc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
11fd0 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
11fe0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  4  /* sqlite3_pc
11ff0 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
12000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12010 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
12020 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74      15  /* sqlit
12030 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
12040 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
12050 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
12060 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
12070 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
12080 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12090 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
120a0 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
120b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
120c0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
120d0 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
120e0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
120f0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
12100 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
12110 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
12120 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12130 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
12140 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
12150 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
12160 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
12170 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
12180 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
12190 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
121a0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
121b0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
121c0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
121d0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
121e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
121f0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
12200 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
12210 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
12220 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
12230 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
12240 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
12250 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
12260 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
12270 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
12280 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
12290 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
122a0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
122b0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
122c0 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
122d0 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
122e0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
122f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
12300 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
12310 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
12320 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
12330 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
12340 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
12350 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
12360 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
12370 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
12380 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
12390 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
123a0 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
123b0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
123c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
123d0 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
123e0 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
123f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
12400 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
12410 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
12420 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
12430 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
12440 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
12450 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
12460 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12470 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
12480 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
12490 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
124a0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
124b0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
124c0 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
124d0 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
124e0 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
124f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12500 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
12510 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
12520 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
12530 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
12540 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
12550 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
12560 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
12570 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
12580 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
12590 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
125a0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
125b0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
125c0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
125d0 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
125e0 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
125f0 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
12600 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
12610 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
12620 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
12630 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
12640 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
12650 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
12660 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
12670 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
12680 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
12690 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
126a0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
126b0 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
126c0 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
126d0 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
126e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
126f0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
12700 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
12710 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
12720 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
12730 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
12740 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
12750 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
12760 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
12770 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
12780 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
12790 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
127a0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
127b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
127c0 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
127d0 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
127e0 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
127f0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
12800 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
12810 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
12820 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
12830 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
12840 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
12850 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
12860 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
12870 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
12880 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
12890 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
128a0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
128b0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
128c0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
128d0 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
128e0 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
128f0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
12900 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
12910 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
12920 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
12930 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
12940 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
12950 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
12960 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
12970 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
12980 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
12990 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
129a0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
129b0 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
129c0 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
129d0 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
129e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
129f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12a00 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
12a10 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
12a20 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
12a30 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
12a40 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
12a50 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
12a60 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
12a70 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
12a80 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
12a90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
12aa0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
12ab0 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
12ac0 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
12ad0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
12ae0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
12af0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
12b00 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
12b10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
12b20 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
12b30 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
12b40 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
12b50 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
12b60 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
12b70 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
12b80 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
12b90 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
12ba0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
12bb0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
12bc0 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
12bd0 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
12be0 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
12bf0 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
12c00 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
12c10 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
12c20 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
12c30 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
12c40 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
12c50 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
12c60 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
12c70 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
12c80 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
12c90 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
12ca0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
12cb0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
12cc0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
12cd0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
12ce0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
12cf0 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
12d00 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
12d10 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
12d20 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
12d30 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
12d40 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
12d50 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
12d60 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
12d70 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
12d80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
12d90 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
12da0 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69  Y     1002  /* i
12db0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
12dc0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
12dd0 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
12de0 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20  R  1003  /* int 
12df0 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
12e00 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
12e10 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
12e20 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
12e30 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
12e40 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
12e50 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
12e60 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
12e70 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
12e80 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
12e90 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
12ea0 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
12eb0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
12ec0 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
12ed0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
12ee0 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
12ef0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
12f00 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
12f10 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
12f20 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
12f30 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
12f40 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
12f50 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
12f60 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45  t Rowid.**.** ^E
12f70 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20  ach entry in an 
12f80 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73  SQLite table has
12f90 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
12fa0 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
12fb0 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
12fc0 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
12fd0 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
12fe0 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
12ff0 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
13000 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
13010 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
13020 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
13030 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
13040 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
13050 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
13060 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
13070 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
13080 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
13090 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
130a0 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
130b0 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
130c0 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
130d0 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
130e0 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
130f0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
13100 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
13110 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
13120 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  nt.** successful
13130 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74   [INSERT] into t
13140 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
13150 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
13160 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  onnection].** in
13170 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13180 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c  ent.  ^As of SQL
13190 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
131a0 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73  7, this routines
131b0 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20  .** records the 
131c0 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69  last insert rowi
131d0 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61  d of both ordina
131e0 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76  ry tables and [v
131f0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a  irtual tables]..
13200 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73  ** ^If no succes
13210 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a  sful [INSERT]s.*
13220 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
13230 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74  rred on that dat
13240 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13250 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  , zero is return
13260 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  ed..**.** ^(If a
13270 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
13280 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
13290 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b  er or within a [
132a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
132b0 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  * method, then t
132c0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
132d0 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
132e0 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
132f0 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f  ted.** row as lo
13300 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
13310 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
13320 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e  le method is run
13330 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
13340 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
13350 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
13360 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20  ethod ends, the 
13370 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
13380 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
13390 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
133a0 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
133b0 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
133c0 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
133d0 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e   method began.)^
133e0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
133f0 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
13400 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
13410 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
13420 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
13430 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
13440 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
13450 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
13460 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
13470 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
13480 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
13490 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
134a0 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
134b0 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
134c0 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
134d0 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
134e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
134f0 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
13500 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
13510 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
13520 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
13530 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
13540 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
13550 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
13560 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
13570 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
13580 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
13590 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
135a0 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
135b0 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
135c0 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
135d0 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
135e0 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
135f0 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
13600 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
13610 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
13620 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
13630 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
13640 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
13650 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
13660 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
13670 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
13680 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
13690 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
136a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
136b0 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
136c0 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
136d0 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
136e0 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
136f0 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
13700 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
13710 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
13720 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
13730 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
13740 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
13750 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
13760 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
13770 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
13780 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
13790 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
137a0 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
137b0 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
137c0 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
137d0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
137e0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
137f0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
13800 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
13810 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
13820 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
13830 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
13840 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
13850 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c   [rowid]..*/.SQL
13860 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
13870 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
13880 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
13890 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
138a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
138b0 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
138c0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
138d0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
138e0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
138f0 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
13900 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
13910 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
13920 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
13930 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
13940 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
13950 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
13960 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
13970 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13980 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
13990 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
139a0 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e  ..** ^(Only chan
139b0 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
139c0 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
139d0 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
139e0 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
139f0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
13a00 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
13a10 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
13a20 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
13a30 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f   triggers or [fo
13a40 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
13a50 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
13a60 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a  ed.)^ Use the.**
13a70 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
13a80 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
13a90 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ion to find the 
13aa0 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
13ab0 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75  changes.** inclu
13ac0 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
13ad0 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20  sed by triggers 
13ae0 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  and foreign key 
13af0 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  actions..**.** ^
13b00 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
13b10 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c  w that are simul
13b20 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54  ated by an [INST
13b30 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a  EAD OF trigger].
13b40 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
13b50 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74  ed.  Only real t
13b60 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65  able changes are
13b70 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
13b80 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  ^(A "row change"
13b90 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
13ba0 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
13bb0 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
13bc0 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
13bd0 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
13be0 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
13bf0 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
13c00 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
13c10 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
13c20 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
13c30 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
13c40 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
13c50 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
13c60 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
13c70 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
13c80 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
13c90 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
13ca0 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
13cb0 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  )^.**.** A "trig
13cc0 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
13cd0 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
13ce0 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
13cf0 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
13d00 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
13d10 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  a [CREATE TRIGGE
13d20 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a  R | trigger]. .*
13d30 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65  * Most SQL state
13d40 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
13d50 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
13d60 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
13d70 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
13d80 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
13d90 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
13da0 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
13db0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
13dc0 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
13dd0 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
13de0 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
13df0 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
13e00 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
13e10 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
13e20 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
13e30 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
13e40 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ion..**.** ^Call
13e50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
13e60 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
13e70 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
13e80 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
13e90 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
13ea0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
13eb0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
13ec0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
13ed0 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
13ee0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
13ef0 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
13f00 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
13f10 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
13f20 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
13f30 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
13f40 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
13f50 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c   ^Thus, when cal
13f60 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
13f70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
13f80 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
13f90 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
13fa0 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
13fb0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
13fc0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
13fd0 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
13fe0 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
13ff0 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57   top level.  ^(W
14000 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
14010 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
14020 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
14030 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
14040 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
14050 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
14060 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
14070 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
14080 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
14090 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
140a0 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
140b0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
140c0 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
140d0 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
140e0 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
140f0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
14100 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
14110 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
14120 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
14130 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
14140 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29  ir own context.)
14150 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
14160 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
14170 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
14180 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
14190 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
141a0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
141b0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
141c0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
141d0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
141e0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
141f0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
14200 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14210 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
14220 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
14230 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
14240 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
14250 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
14260 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
14270 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53  meaningful..*/.S
14280 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
14290 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
142a0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
142b0 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
142c0 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
142d0 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54  odified.**.** ^T
142e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
142f0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
14300 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
14310 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54  aused by [INSERT
14320 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f  ],.** [UPDATE] o
14330 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
14340 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20  ments since the 
14350 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14360 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64  tion] was opened
14370 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74  ..** ^(The count
14380 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
14390 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
143a0 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  es() includes al
143b0 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f  l changes.** fro
143c0 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52  m all [CREATE TR
143d0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
143e0 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68   contexts and ch
143f0 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a  anges made by.**
14400 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
14410 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c  tions]. However,
14420 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f  .** the count do
14430 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
14440 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69  hanges used to i
14450 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43  mplement [REPLAC
14460 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a  E] constraints,.
14470 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20  ** do rollbacks 
14480 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  or ABORT process
14490 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41  ing, or [DROP TA
144a0 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e  BLE] processing.
144b0 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64    The.** count d
144c0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
144d0 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68  rows of views th
144e0 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54  at fire an [INST
144f0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c  EAD OF trigger],
14500 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68  .** though if th
14510 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  e INSTEAD OF tri
14520 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67  gger makes chang
14530 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74  es of its own, t
14540 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a  hose changes .**
14550 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a   are counted.)^.
14560 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
14570 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
14580 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20  function counts 
14590 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73  the changes as s
145a0 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74  oon as.** the st
145b0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
145c0 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c  es them is compl
145d0 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
145e0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a  tatement handle.
145f0 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  ** is passed to 
14600 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
14610 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
14620 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
14630 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
14640 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
14650 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
14660 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
14670 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
14680 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
14690 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
146a0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
146b0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
146c0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
146d0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
146e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
146f0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
14700 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
14710 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
14720 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
14730 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
14740 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
14750 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53  meaningful..*/.S
14760 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
14770 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
14780 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
14790 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
147a0 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
147b0 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
147c0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
147d0 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
147e0 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
147f0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
14800 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
14810 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
14820 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
14830 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
14840 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
14850 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
14860 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
14870 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
14880 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
14890 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
148a0 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
148b0 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
148c0 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
148d0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
148e0 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
148f0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
14900 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
14910 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
14920 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
14930 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
14940 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
14950 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
14960 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
14970 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
14980 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
14990 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
149a0 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
149b0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
149c0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
149d0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
149e0 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
149f0 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
14a00 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
14a10 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
14a20 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
14a30 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
14a40 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
14a50 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
14a60 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
14a70 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
14a80 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
14a90 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
14aa0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
14ab0 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
14ac0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
14ad0 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
14ae0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
14af0 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
14b00 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
14b10 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
14b20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
14b30 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
14b40 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
14b50 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
14b60 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
14b70 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
14b80 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
14b90 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
14ba0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
14bb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
14bc0 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
14bd0 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
14be0 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
14bf0 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
14c00 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
14c10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14c20 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
14c30 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
14c40 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
14c50 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
14c60 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
14c70 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
14c80 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
14c90 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
14ca0 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
14cb0 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
14cc0 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
14cd0 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
14ce0 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
14cf0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
14d00 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
14d10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
14d20 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
14d30 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
14d40 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
14d50 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
14d60 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
14d70 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
14d80 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
14d90 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
14da0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
14db0 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
14dc0 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
14dd0 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
14de0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
14df0 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
14e00 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
14e10 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
14e20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
14e30 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
14e40 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
14e50 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
14e60 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
14e70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
14e80 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
14e90 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
14ea0 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
14eb0 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
14ec0 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
14ed0 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
14ee0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e   void sqlite3_in
14ef0 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
14f00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
14f10 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
14f20 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
14f30 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
14f40 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
14f50 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
14f60 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
14f70 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
14f80 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
14f90 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
14fa0 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
14fb0 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
14fc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
14fd0 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
14fe0 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
14ff0 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
15000 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
15010 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
15020 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
15030 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
15040 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
15050 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
15060 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
15070 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
15080 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
15090 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
150a0 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
150b0 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
150c0 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
150d0 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
150e0 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
150f0 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
15100 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
15110 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
15120 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
15130 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
15140 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
15150 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
15160 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
15170 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
15180 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
15190 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
151a0 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
151b0 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
151c0 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
151d0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
151e0 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
151f0 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
15200 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
15210 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
15220 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
15230 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
15240 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
15250 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
15260 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
15270 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
15280 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
15290 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
152a0 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
152b0 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
152c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
152d0 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
152e0 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
152f0 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
15300 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
15310 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
15320 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
15330 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
15340 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
15350 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
15360 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
15370 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
15380 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
15390 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
153a0 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
153b0 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
153c0 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
153d0 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
153e0 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
153f0 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
15400 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
15410 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
15420 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
15430 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
15440 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
15450 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
15460 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
15470 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
15480 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
15490 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
154a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
154b0 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
154c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
154d0 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
154e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
154f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
15500 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
15510 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
15520 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
15530 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
15540 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53  byte order..*/.S
15550 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
15560 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
15570 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
15580 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
15590 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
155a0 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
155b0 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
155c0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
155d0 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
155e0 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
155f0 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  Errors.**.** ^Th
15600 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
15610 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
15620 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62  ion that might b
15630 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
15640 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
15650 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
15660 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
15670 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  e that another t
15680 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
15690 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a  ess has locked..
156a0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
156b0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
156c0 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
156d0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
156e0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
156f0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
15700 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
15710 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
15720 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
15730 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
15740 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
15750 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
15760 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
15770 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
15780 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
15790 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
157a0 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
157b0 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
157c0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
157d0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
157e0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
157f0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
15800 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
15810 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
15820 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
15830 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
15840 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
15850 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
15860 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
15870 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
15880 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f  oked for this lo
15890 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
158a0 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
158b0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
158c0 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
158d0 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
158e0 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
158f0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
15900 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
15910 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
15920 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
15930 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66  returned..** ^If
15940 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
15950 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
15960 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
15970 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
15980 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
15990 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
159a0 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
159b0 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
159c0 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
159d0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
159e0 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
159f0 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
15a00 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
15a10 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
15a20 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
15a30 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
15a40 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
15a50 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
15a60 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
15a70 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
15a80 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
15a90 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
15aa0 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
15ab0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
15ac0 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
15ad0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
15ae0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
15af0 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
15b00 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
15b10 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
15b20 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
15b30 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
15b40 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
15b50 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
15b60 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
15b70 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
15b80 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
15b90 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
15ba0 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
15bb0 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
15bc0 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
15bd0 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
15be0 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
15bf0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
15c00 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
15c10 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
15c20 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
15c30 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
15c40 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
15c50 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
15c60 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
15c70 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
15c80 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
15c90 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
15ca0 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
15cb0 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
15cc0 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
15cd0 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
15ce0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
15cf0 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
15d00 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
15d10 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
15d20 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
15d30 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
15d40 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
15d50 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
15d60 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
15d70 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
15d80 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
15d90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
15da0 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
15db0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
15dc0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
15dd0 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
15de0 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
15df0 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
15e00 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
15e10 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
15e20 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
15e30 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
15e40 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
15e50 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
15e60 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
15e70 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
15e80 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
15e90 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
15ea0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
15eb0 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
15ec0 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
15ed0 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
15ee0 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
15ef0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
15f00 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
15f10 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
15f20 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20  ers.  ^If it is 
15f30 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
15f40 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
15f50 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
15f60 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
15f70 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
15f80 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
15f90 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
15fa0 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
15fb0 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
15fc0 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
15fd0 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
15fe0 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
15ff0 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
16000 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73  BLOCKED].  ^This
16010 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d   error code prom
16020 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20  otion.** forces 
16030 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c  an automatic rol
16040 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61  lback of the cha
16050 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a  nges.  See the.*
16060 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74  * <a href="/cvst
16070 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75  rac/wiki?p=Corru
16080 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
16090 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72  syError">.** Cor
160a0 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
160b0 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69  BusyError</a> wi
160c0 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69  ki page for a di
160d0 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a  scussion of why.
160e0 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72  ** this is impor
160f0 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tant..**.** ^(Th
16100 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
16110 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
16120 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
16130 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
16140 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
16150 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
16160 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
16170 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
16180 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
16190 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
161a0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
161b0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
161c0 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
161d0 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
161e0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
161f0 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
16200 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
16210 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
16220 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
16230 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
16240 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
16250 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
16260 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75  handler.  Any su
16270 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
16280 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
16290 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
162a0 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
162b0 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
162c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
162d0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
162e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
162f0 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
16300 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
16310 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  r..*/.SQLITE_API
16320 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73   int sqlite3_bus
16330 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
16340 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
16350 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
16360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16370 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
16380 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ut.**.** ^This r
16390 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
163a0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
163b0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
163c0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
163d0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
163e0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
163f0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
16400 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
16410 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
16420 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
16430 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
16440 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
16450 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
16460 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
16470 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
16480 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
16490 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
164a0 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
164b0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
164c0 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
164d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
164e0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
164f0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
16500 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
16510 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  D]..**.** ^Calli
16520 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
16530 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
16540 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
16550 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
16560 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
16570 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
16580 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
16590 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
165a0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
165b0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
165c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
165d0 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
165e0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
165f0 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
16600 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
16610 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
16620 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
16630 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
16640 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
16650 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
16660 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
16670 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f  is cleared.)^.*/
16680 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
16690 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
166a0 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
166b0 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
166c0 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
166d0 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
166e0 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
166f0 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  s.**.** This is 
16700 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  a legacy interfa
16710 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65  ce that is prese
16720 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rved for backwar
16730 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
16740 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73  ..** Use of this
16750 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
16760 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  t recommended..*
16770 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
16780 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
16790 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
167a0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
167b0 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
167c0 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
167d0 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
167e0 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
167f0 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
16800 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
16810 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
16820 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
16830 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
16840 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
16850 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
16860 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
16870 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
16880 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
16890 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
168a0 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
168b0 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
168c0 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
168d0 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
168e0 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
168f0 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
16900 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
16910 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
16920 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
16930 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
16940 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
16950 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
16960 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
16970 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
16980 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
16990 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
169a0 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
169b0 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
169c0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
169d0 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
169e0 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
169f0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
16a00 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
16a10 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
16a20 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
16a30 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
16a40 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
16a50 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
16a60 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
16a70 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
16a80 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
16a90 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
16aa0 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
16ab0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
16ac0 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
16ad0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
16ae0 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
16af0 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
16b00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16b10 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
16b20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
16b30 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
16b40 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
16b50 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
16b60 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
16b70 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
16b80 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
16b90 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
16ba0 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78  **.** ^(As an ex
16bb0 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
16bc0 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
16bd0 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
16be0 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
16bf0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
16c00 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
16c10 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
16c20 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
16c30 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
16c40 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
16c50 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
16c60 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
16c70 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
16c80 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
16c90 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
16ca0 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
16cb0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
16cc0 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
16cd0 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
16ce0 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
16cf0 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
16d00 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
16d10 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
16d20 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
16d30 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
16d40 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
16d50 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
16d60 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
16d70 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
16d80 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
16d90 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
16da0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
16db0 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
16dc0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
16dd0 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
16de0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
16df0 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
16e00 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
16e10 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
16e20 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
16e30 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
16e40 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
16e50 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
16e60 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
16e70 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
16e80 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
16e90 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
16ea0 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
16eb0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
16ec0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
16ed0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
16ee0 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
16ef0 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
16f00 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
16f10 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
16f20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
16f30 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
16f40 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
16f50 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
16f60 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
16f70 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
16f80 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
16f90 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
16fa0 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
16fb0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
16fc0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
16fd0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
16fe0 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  th the result fr
16ff0 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  om sqlite3_get_t
17000 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75  able(),.** it mu
17010 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75  st pass the resu
17020 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72  lt table pointer
17030 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
17040 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
17050 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
17060 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
17070 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
17080 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
17090 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
170a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
170b0 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
170c0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
170d0 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
170e0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
170f0 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
17100 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
17110 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
17120 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
17130 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
17140 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
17150 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
17160 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
17170 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
17180 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
17190 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
171a0 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
171b0 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
171c0 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
171d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
171e0 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
171f0 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
17200 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
17210 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
17220 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
17230 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
17240 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
17250 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
17260 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
17270 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
17280 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
17290 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
172a0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
172b0 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
172c0 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
172d0 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
172e0 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
172f0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
17300 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
17310 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
17320 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  msg()]..*/.SQLIT
17330 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
17340 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
17350 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
17360 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
17370 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
17380 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
17390 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
173a0 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
173b0 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c  char ***pazResul
173c0 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73  t,    /* Results
173d0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
173e0 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20  .  int *pnRow,  
173f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
17400 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
17410 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
17420 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d  /.  int *pnColum
17430 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  n,        /* Num
17440 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
17450 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
17460 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70  re */.  char **p
17470 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a  zErrmsg       /*
17480 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
17490 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51  en here */.);.SQ
174a0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
174b0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
174c0 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
174d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
174e0 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
174f0 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
17500 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
17510 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
17520 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
17530 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
17540 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
17550 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
17560 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
17570 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
17580 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
17590 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
175a0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
175b0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
175c0 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
175d0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
175e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
175f0 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
17600 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
17610 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
17620 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
17630 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
17640 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
17650 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
17660 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
17670 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
17680 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
17690 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
176a0 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
176b0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
176c0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
176d0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
176e0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
176f0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
17700 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
17710 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
17720 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
17730 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
17740 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
17750 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
17760 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
17770 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
17780 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
17790 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
177a0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
177b0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
177c0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
177d0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
177e0 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
177f0 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
17800 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
17810 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
17820 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
17830 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
17840 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
17850 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
17860 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
17870 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
17880 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
17890 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
178a0 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
178b0 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
178c0 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
178d0 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
178e0 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
178f0 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
17900 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
17910 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
17920 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
17930 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
17940 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
17950 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
17960 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
17970 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
17980 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
17990 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
179a0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
179b0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
179c0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
179d0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
179e0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
179f0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
17a00 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
17a10 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
17a20 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
17a30 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
17a40 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
17a50 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
17a60 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
17a70 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
17a80 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
17a90 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
17aa0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
17ab0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
17ac0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
17ad0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
17ae0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
17af0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
17b00 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
17b10 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
17b20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
17b30 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
17b40 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
17b50 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
17b60 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
17b70 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
17b80 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
17b90 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
17ba0 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
17bb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
17bc0 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
17bd0 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
17be0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
17bf0 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
17c00 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
17c10 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
17c20 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
17c30 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
17c40 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
17c50 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
17c60 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
17c70 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64   null-terminated
17c80 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
17c90 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
17ca0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
17cb0 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
17cc0 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
17cd0 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
17ce0 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
17cf0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
17d00 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
17d10 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
17d20 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
17d30 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
17d40 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
17d50 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
17d60 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
17d70 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
17d80 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
17d90 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
17da0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
17db0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
17dc0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
17dd0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
17de0 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
17df0 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
17e00 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
17e10 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
17e20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
17e30 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
17e40 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
17e50 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
17e60 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
17e70 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
17e80 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
17e90 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
17ea0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
17eb0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
17ec0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
17ed0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
17ee0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
17ef0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
17f00 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
17f10 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
17f20 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
17f30 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
17f40 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
17f50 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
17f60 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
17f70 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
17f80 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
17f90 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
17fa0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
17fb0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
17fc0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
17fd0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
17fe0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
17ff0 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
18000 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
18010 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
18020 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
18030 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
18040 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
18050 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
18060 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
18070 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
18080 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
18090 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
180a0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
180b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
180c0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
180d0 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
180e0 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
180f0 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
18100 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
18110 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
18120 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
18130 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
18140 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
18150 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
18160 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
18170 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
18180 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
18190 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
181a0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
181b0 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
181c0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
181d0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
181e0 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
181f0 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
18200 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
18210 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
18220 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
18230 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
18240 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
18250 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
18260 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
18270 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
18280 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
18290 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
182a0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
182b0 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
182c0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
182d0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
182e0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
182f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
18300 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
18310 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
18320 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
18330 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
18340 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
18350 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
18360 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
18370 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
18380 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
18390 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
183a0 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
183b0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
183c0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
183d0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
183e0 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
183f0 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
18400 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
18410 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
18420 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
18430 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
18440 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
18450 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51   string.)^.*/.SQ
18460 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
18470 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
18480 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
18490 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
184a0 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
184b0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
184c0 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45  va_list);.SQLITE
184d0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
184e0 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
184f0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
18500 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  *, ...);.SQLITE_
18510 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
18520 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
18530 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
18540 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
18550 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
18560 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
18570 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
18580 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
18590 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
185a0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
185b0 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
185c0 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
185d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
185e0 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
185f0 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
18600 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
18610 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
18620 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
18630 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
18640 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
18650 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
18660 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
18670 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
18680 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
18690 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
186a0 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
186b0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
186c0 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
186d0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
186e0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
186f0 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
18700 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
18710 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
18720 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
18730 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
18740 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
18750 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
18760 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
18770 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
18780 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
18790 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
187a0 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
187b0 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
187c0 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
187d0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
187e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
187f0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
18800 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
18810 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
18820 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
18830 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
18840 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18850 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
18860 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
18870 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
18880 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
18890 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
188a0 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
188b0 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
188c0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
188d0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
188e0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
188f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
18900 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
18910 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
18920 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
18930 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
18940 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
18950 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
18960 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
18970 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
18980 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
18990 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
189a0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
189b0 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
189c0 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
189d0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
189e0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
189f0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
18a00 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
18a10 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
18a20 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
18a30 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
18a40 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
18a50 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
18a60 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
18a70 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
18a80 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
18a90 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
18aa0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
18ab0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
18ac0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
18ad0 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
18ae0 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
18af0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
18b00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18b10 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
18b20 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
18b30 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
18b40 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
18b50 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72  .)^ ^ If the fir
18b60 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
18b70 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
18b80 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
18b90 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
18ba0 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
18bb0 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
18bc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
18bd0 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
18be0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
18bf0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
18c00 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
18c10 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
18c20 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
18c30 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
18c40 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
18c50 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
18c60 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
18c70 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
18c80 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
18c90 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
18ca0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
18cb0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
18cc0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
18cd0 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
18ce0 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
18cf0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
18d00 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
18d10 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
18d20 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
18d30 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
18d40 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
18d50 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
18d60 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
18d70 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
18d80 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
18d90 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
18da0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
18db0 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
18dc0 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
18dd0 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
18de0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
18df0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e  te3_realloc() an
18e00 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
18e10 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
18e20 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
18e30 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
18e40 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
18e50 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
18e60 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
18e70 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  d..**.** ^The me
18e80 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
18e90 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
18ea0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
18eb0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
18ec0 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
18ed0 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
18ee0 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
18ef0 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
18f00 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
18f10 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
18f20 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
18f30 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
18f40 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
18f50 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
18f60 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
18f70 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
18f80 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
18f90 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
18fa0 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
18fb0 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
18fc0 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
18fd0 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
18fe0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
18ff0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
19000 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
19010 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
19020 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
19030 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
19040 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
19050 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
19060 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f  .**.** The Windo
19070 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
19080 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74  layer calls.** t
19090 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
190a0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
190b0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
190c0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
190d0 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
190e0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
190f0 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
19100 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
19110 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
19120 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
19130 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
19140 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
19150 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
19160 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65  ation errors are
19170 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
19180 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72  * they are repor
19190 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
191a0 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
191b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
191c0 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
191d0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
191e0 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
191f0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
19200 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
19210 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
19220 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
19230 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
19240 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
19250 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
19260 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
19270 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
19280 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
19290 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
192a0 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
192b0 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
192c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
192d0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
192e0 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
192f0 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
19300 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
19310 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
19320 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
19330 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
19340 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
19350 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
19360 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
19370 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
19380 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  c(int);.SQLITE_A
19390 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
193a0 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
193b0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
193c0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72   void sqlite3_fr
193d0 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
193e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
193f0 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
19400 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
19410 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
19420 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
19430 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
19440 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
19450 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
19460 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
19470 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
19480 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
19490 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
194a0 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
194b0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
194c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
194d0 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
194e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
194f0 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
19500 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
19510 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
19520 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
19530 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
19540 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
19550 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
19560 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
19570 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
19580 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
19590 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
195a0 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
195b0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
195c0 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
195d0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
195e0 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
195f0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
19600 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
19610 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
19620 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
19630 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
19640 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
19650 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
19660 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
19670 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
19680 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
19690 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
196a0 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
196b0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
196c0 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
196d0 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
196e0 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
196f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
19700 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
19710 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
19720 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
19730 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
19740 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
19750 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
19760 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
19770 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
19780 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
19790 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
197a0 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
197b0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
197c0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
197d0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
197e0 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
197f0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
19800 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
19810 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
19820 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
19830 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
19840 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  sed(void);.SQLIT
19850 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
19860 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
19870 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
19880 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
19890 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
198a0 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
198b0 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
198c0 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
198d0 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
198e0 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
198f0 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
19900 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
19910 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
19920 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
19930 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
19940 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
19950 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
19960 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
19970 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
19980 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
19990 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
199a0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
199b0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
199c0 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
199d0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
199e0 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
199f0 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
19a00 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
19a10 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
19a20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
19a30 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
19a40 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
19a50 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
19a60 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
19a70 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
19a80 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
19a90 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ime this routine
19aa0 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74   is invoked (eit
19ab0 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f  her internally o
19ac0 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c  r by.** the appl
19ad0 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e  ication) the PRN
19ae0 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e  G is seeded usin
19af0 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
19b00 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68  ained.** from th
19b10 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
19b20 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
19b30 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
19b40 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e  ] object..** ^On
19b50 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
19b60 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
19b70 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
19b80 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
19b90 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
19ba0 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
19bb0 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
19bc0 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
19bd0 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
19be0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
19bf0 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
19c00 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
19c10 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
19c20 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
19c30 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
19c40 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
19c50 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
19c60 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
19c70 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19c80 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
19c90 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
19ca0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
19cb0 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
19cc0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
19cd0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
19ce0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
19cf0 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
19d00 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
19d10 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
19d20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
19d30 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
19d40 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
19d50 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
19d60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
19d70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
19d80 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
19d90 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
19da0 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
19db0 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
19dc0 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
19dd0 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
19de0 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
19df0 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
19e00 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
19e10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
19e20 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
19e30 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
19e40 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
19e50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19e60 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
19e70 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
19e80 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
19e90 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
19ea0 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
19eb0 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
19ec0 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
19ed0 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
19ee0 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
19ef0 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
19f00 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
19f10 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
19f20 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
19f30 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
19f40 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
19f50 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
19f60 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
19f70 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
19f80 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
19f90 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
19fa0 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
19fb0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
19fc0 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
19fd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
19fe0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
19ff0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1a000 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
1a010 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
1a020 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1a030 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
1a040 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
1a050 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1a060 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
1a070 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
1a080 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
1a090 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
1a0a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1a0b0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
1a0c0 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
1a0d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1a0e0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1a0f0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1a100 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
1a110 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1a120 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1a130 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
1a140 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
1a150 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
1a160 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
1a170 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1a180 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1a190 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
1a1a0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
1a1b0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
1a1c0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1a1d0 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
1a1e0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
1a1f0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
1a200 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1a210 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
1a220 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
1a230 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
1a240 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
1a250 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
1a260 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
1a270 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
1a280 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
1a290 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
1a2a0 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
1a2b0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1a2c0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
1a2d0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
1a2e0 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
1a2f0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1a300 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
1a310 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1a320 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
1a330 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
1a340 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1a350 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1a360 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
1a370 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
1a380 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
1a390 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
1a3a0 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
1a3b0 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
1a3c0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
1a3d0 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
1a3e0 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
1a3f0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
1a400 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
1a410 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
1a420 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
1a430 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1a440 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
1a450 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
1a460 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
1a470 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
1a480 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
1a490 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1a4a0 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
1a4b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1a4c0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
1a4d0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1a4e0 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
1a4f0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
1a500 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
1a510 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
1a520 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
1a530 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
1a540 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
1a550 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
1a560 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
1a570 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
1a580 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
1a590 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
1a5a0 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
1a5b0 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
1a5c0 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
1a5d0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1a5e0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
1a5f0 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
1a600 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
1a610 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
1a620 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
1a630 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
1a640 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
1a650 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
1a660 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
1a670 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
1a680 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1a690 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
1a6a0 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
1a6b0 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
1a6c0 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
1a6d0 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
1a6e0 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
1a6f0 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
1a700 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
1a710 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
1a720 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
1a730 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
1a740 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
1a750 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
1a760 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
1a770 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
1a780 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
1a790 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
1a7a0 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1a7b0 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
1a7c0 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
1a7d0 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
1a7e0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
1a7f0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1a800 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
1a810 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
1a820 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1a830 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
1a840 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
1a850 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
1a860 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
1a870 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
1a880 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
1a890 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
1a8a0 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
1a8b0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
1a8c0 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
1a8d0 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
1a8e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
1a8f0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
1a900 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
1a910 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
1a920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1a930 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
1a940 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
1a950 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1a960 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
1a970 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
1a980 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
1a990 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
1a9a0 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
1a9b0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
1a9c0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
1a9d0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
1a9e0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
1a9f0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1aa00 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1aa10 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1aa20 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1aa30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1aa40 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1aa50 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1aa60 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
1aa70 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1aa80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1aa90 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1aaa0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1aab0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1aac0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1aad0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1aae0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1aaf0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1ab00 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
1ab10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1ab20 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
1ab30 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
1ab40 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
1ab50 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
1ab60 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
1ab70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
1ab80 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
1ab90 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
1aba0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1abb0 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
1abc0 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
1abd0 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
1abe0 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
1abf0 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
1ac00 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1ac10 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
1ac20 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1ac30 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1ac40 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
1ac50 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
1ac60 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1ac70 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
1ac80 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
1ac90 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
1aca0 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
1acb0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
1acc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
1acd0 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
1ace0 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
1acf0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
1ad00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
1ad10 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
1ad20 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
1ad30 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
1ad40 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
1ad50 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
1ad60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1ad70 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1ad80 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
1ad90 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
1ada0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
1adb0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1adc0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1add0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
1ade0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
1adf0 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
1ae00 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1ae10 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
1ae20 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1ae30 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1ae40 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
1ae50 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
1ae60 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
1ae70 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
1ae80 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
1ae90 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
1aea0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
1aeb0 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
1aec0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1aed0 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
1aee0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
1aef0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1af00 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1af10 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
1af20 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
1af30 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
1af40 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
1af50 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
1af60 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
1af70 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c  s a [SQLITE_ROLL
1af80 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f  BACK | return co
1af90 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  de].** from the 
1afa0 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
1afb0 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
1afc0 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
1afd0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
1afe0 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
1aff0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1b000 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
1b010 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b020 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
1b030 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
1b040 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
1b050 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
1b060 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b070 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
1b080 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
1b090 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1b0a0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
1b0b0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
1b0c0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
1b0d0 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
1b0e0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
1b0f0 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
1b100 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
1b110 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
1b120 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1b130 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1b140 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
1b150 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
1b160 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
1b170 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
1b180 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
1b190 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
1b1a0 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
1b1b0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1b1c0 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
1b1d0 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
1b1e0 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
1b1f0 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
1b200 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
1b210 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
1b220 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
1b230 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
1b240 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
1b250 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
1b260 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1b270 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
1b280 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
1b290 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
1b2a0 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
1b2b0 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
1b2c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1b2d0 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
1b2e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1b2f0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
1b300 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
1b310 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
1b320 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
1b330 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
1b340 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
1b350 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
1b360 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1b370 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
1b380 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1b390 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
1b3a0 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
1b3b0 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
1b3c0 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
1b3d0 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
1b3e0 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
1b3f0 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
1b400 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
1b410 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
1b420 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
1b430 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b440 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b450 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
1b460 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
1b470 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
1b480 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
1b490 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
1b4a0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1b4b0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1b4c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b4d0 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
1b4e0 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
1b4f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b500 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b510 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b520 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
1b530 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
1b540 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1b550 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b560 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b570 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
1b580 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
1b590 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1b5a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b5b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b5c0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
1b5d0 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
1b5e0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1b5f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1b600 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b610 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
1b620 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
1b630 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1b640 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b650 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1b660 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
1b670 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
1b680 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1b690 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1b6a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1b6b0 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
1b6c0 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
1b6d0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1b6e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1b6f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
1b700 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
1b710 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
1b720 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1b730 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b740 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1b750 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1b760 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
1b770 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1b780 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1b790 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1b7a0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
1b7b0 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
1b7c0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1b7d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b7e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1b7f0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
1b800 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
1b810 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1b820 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1b830 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1b840 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
1b850 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b860 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b870 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b880 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1b890 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
1b8a0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1b8b0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1b8c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b8d0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1b8e0 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
1b8f0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1b900 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b910 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b920 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
1b930 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
1b940 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1b950 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b960 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b970 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
1b980 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
1b990 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1b9a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b9b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b9c0 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
1b9d0 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
1b9e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b9f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ba00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ba10 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
1ba20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
1ba30 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
1ba40 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
1ba50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ba60 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
1ba70 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
1ba80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1ba90 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1baa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1bab0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
1bac0 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
1bad0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
1bae0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1baf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bb00 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
1bb10 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
1bb20 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
1bb30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1bb40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
1bb50 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
1bb60 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
1bb70 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
1bb80 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
1bb90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
1bba0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1bbb0 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
1bbc0 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
1bbd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1bbe0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
1bbf0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1bc00 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
1bc10 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
1bc20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1bc30 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
1bc40 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
1bc50 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
1bc60 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
1bc70 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1bc80 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
1bc90 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
1bca0 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
1bcb0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1bcc0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1bcd0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
1bce0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
1bcf0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1bd00 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1bd10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1bd20 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1bd30 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
1bd40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1bd50 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1bd60 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1bd70 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
1bd80 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
1bd90 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1bda0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1bdb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1bdc0 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
1bdd0 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
1bde0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1bdf0 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
1be00 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
1be10 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
1be20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
1be30 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
1be40 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
1be50 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
1be60 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
1be70 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
1be80 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
1be90 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1bea0 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
1beb0 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
1bec0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1bed0 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
1bee0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1bef0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
1bf00 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
1bf10 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
1bf20 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
1bf30 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
1bf40 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1bf50 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1bf60 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1bf70 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1bf80 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
1bf90 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
1bfa0 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
1bfb0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
1bfc0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
1bfd0 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
1bfe0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
1bff0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1c000 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
1c010 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
1c020 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1c030 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
1c040 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
1c050 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
1c060 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
1c070 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1c080 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
1c090 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
1c0a0 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
1c0b0 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
1c0c0 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
1c0d0 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
1c0e0 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
1c0f0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
1c100 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
1c110 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
1c120 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1c130 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1c140 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
1c150 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
1c160 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
1c170 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
1c180 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
1c190 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
1c1a0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
1c1b0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
1c1c0 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
1c1d0 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
1c1e0 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
1c1f0 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
1c200 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
1c210 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
1c220 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
1c230 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
1c240 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
1c250 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
1c260 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
1c270 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
1c280 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
1c290 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
1c2a0 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
1c2b0 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
1c2c0 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
1c2d0 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
1c2e0 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
1c2f0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
1c300 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
1c310 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
1c320 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
1c330 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
1c340 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
1c350 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
1c360 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
1c370 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
1c380 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
1c390 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
1c3a0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1c3b0 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te..*/.SQLITE_AP
1c3c0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
1c3d0 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
1c3e0 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
1c3f0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
1c400 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
1c410 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45  _API SQLITE_EXPE
1c420 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
1c430 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
1c440 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
1c450 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
1c460 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
1c470 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
1c480 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1c490 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
1c4a0 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
1c4b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c4c0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1c4d0 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
1c4e0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
1c4f0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
1c500 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
1c510 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
1c520 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
1c530 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
1c540 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
1c550 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
1c560 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
1c570 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1c580 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
1c590 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
1c5a0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
1c5b0 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
1c5c0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
1c5d0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
1c5e0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
1c5f0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
1c600 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
1c610 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
1c620 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
1c630 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
1c640 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1c650 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
1c660 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d  ter N is the num
1c670 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
1c680 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
1c690 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
1c6a0 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
1c6b0 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
1c6c0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
1c6d0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
1c6e0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
1c6f0 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
1c700 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
1c710 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
1c720 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
1c730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
1c740 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
1c750 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1c760 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
1c770 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
1c780 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
1c790 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
1c7a0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1c7b0 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
1c7c0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
1c7d0 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
1c7e0 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
1c7f0 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
1c800 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
1c810 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
1c820 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1c830 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
1c840 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
1c850 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
1c860 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
1c870 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1c880 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
1c890 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
1c8a0 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
1c8b0 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
1c8c0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1c8d0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
1c8e0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1c8f0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1c900 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1c910 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1c920 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
1c930 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
1c940 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1c950 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1c960 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1c970 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1c980 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1c990 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1c9a0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1c9b0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1c9c0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1c9d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1c9e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
1c9f0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
1ca00 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
1ca10 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
1ca20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ca30 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
1ca40 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
1ca50 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
1ca60 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
1ca70 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
1ca80 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
1ca90 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
1caa0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1cab0 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
1cac0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
1cad0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
1cae0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
1caf0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1cb00 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
1cb10 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
1cb20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
1cb30 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
1cb40 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
1cb50 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
1cb60 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
1cb70 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
1cb80 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
1cb90 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
1cba0 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
1cbb0 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
1cbc0 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
1cbd0 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
1cbe0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
1cbf0 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
1cc00 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
1cc10 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
1cc20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
1cc30 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
1cc40 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
1cc50 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
1cc60 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
1cc70 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1cc80 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
1cc90 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
1cca0 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
1ccb0 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
1ccc0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
1ccd0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1cce0 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
1ccf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1cd00 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
1cd10 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
1cd20 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
1cd30 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
1cd40 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
1cd50 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
1cd60 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
1cd70 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
1cd80 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
1cd90 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
1cda0 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
1cdb0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
1cdc0 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
1cdd0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1cde0 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
1cdf0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1ce00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1ce10 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
1ce20 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
1ce30 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1ce40 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
1ce50 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
1ce60 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
1ce70 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
1ce80 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
1ce90 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
1cea0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1ceb0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
1cec0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1ced0 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
1cee0 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
1cef0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
1cf00 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
1cf10 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
1cf20 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
1cf30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
1cf40 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
1cf50 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
1cf60 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
1cf70 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1cf80 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
1cf90 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
1cfa0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
1cfb0 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
1cfc0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1cfd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
1cfe0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
1cff0 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
1d000 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
1d010 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
1d020 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
1d030 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
1d040 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
1d050 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
1d060 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1d070 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1d080 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
1d090 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1d0a0 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
1d0b0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
1d0c0 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
1d0d0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
1d0e0 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
1d0f0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
1d100 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1d110 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
1d120 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1d130 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
1d140 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
1d150 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1d160 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
1d170 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1d180 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1d190 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1d1a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1d1b0 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
1d1c0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1d1d0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1d1e0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1d1f0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
1d200 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
1d210 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
1d220 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
1d230 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
1d240 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
1d250 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
1d260 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
1d270 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
1d280 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
1d290 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1d2a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1d2b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1d2c0 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
1d2d0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
1d2e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1d2f0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1d300 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
1d310 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
1d320 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
1d330 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
1d340 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
1d350 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
1d360 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
1d370 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
1d380 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1d390 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
1d3a0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
1d3b0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
1d3c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1d3d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1d3e0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
1d3f0 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
1d400 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
1d410 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1d420 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
1d430 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1d440 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
1d450 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
1d460 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1d470 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
1d480 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
1d490 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1d4a0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
1d4b0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1d4c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1d4d0 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
1d4e0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
1d4f0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
1d500 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
1d510 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
1d520 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
1d530 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1d540 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
1d550 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
1d560 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
1d570 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
1d580 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1d590 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
1d5a0 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
1d5b0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
1d5c0 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
1d5d0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
1d5e0 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
1d5f0 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
1d600 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1d610 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
1d620 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1d630 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
1d640 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
1d650 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
1d660 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
1d670 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
1d680 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
1d690 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1d6a0 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
1d6b0 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
1d6c0 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
1d6d0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
1d6e0 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
1d6f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1d700 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
1d710 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
1d720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d730 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
1d740 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
1d750 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
1d760 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
1d770 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
1d780 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1d790 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1d7a0 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
1d7b0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
1d7c0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1d7d0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
1d7e0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1d7f0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
1d800 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
1d810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d820 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
1d830 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
1d840 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
1d850 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1d860 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
1d870 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1d880 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
1d890 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
1d8a0 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
1d8b0 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
1d8c0 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
1d8d0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
1d8e0 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
1d8f0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
1d900 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
1d910 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
1d920 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
1d930 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1d940 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1d950 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
1d960 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
1d970 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
1d980 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
1d990 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
1d9a0 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
1d9b0 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
1d9c0 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
1d9d0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
1d9e0 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
1d9f0 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
1da00 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
1da10 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
1da20 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
1da30 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
1da40 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
1da50 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
1da60 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
1da70 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
1da80 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
1da90 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
1daa0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1dab0 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
1dac0 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
1dad0 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
1dae0 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
1daf0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
1db00 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1db10 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
1db20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
1db30 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1db40 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
1db50 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
1db60 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
1db70 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
1db80 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
1db90 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
1dba0 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
1dbb0 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
1dbc0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1dbd0 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
1dbe0 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
1dbf0 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
1dc00 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1dc10 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
1dc20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
1dc30 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
1dc40 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
1dc50 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
1dc60 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
1dc70 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
1dc80 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
1dc90 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
1dca0 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
1dcb0 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
1dcc0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
1dcd0 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
1dce0 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
1dcf0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
1dd00 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
1dd10 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
1dd20 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
1dd30 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
1dd40 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
1dd50 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
1dd60 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
1dd70 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
1dd80 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
1dd90 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
1dda0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
1ddb0 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
1ddc0 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
1ddd0 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
1dde0 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
1ddf0 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
1de00 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1de10 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1de20 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
1de30 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
1de40 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
1de50 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
1de60 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
1de70 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
1de80 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
1de90 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
1dea0 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
1deb0 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
1dec0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
1ded0 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
1dee0 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
1def0 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
1df00 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1df10 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
1df20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
1df30 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
1df40 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
1df50 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
1df60 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
1df70 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
1df80 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
1df90 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1dfa0 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
1dfb0 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
1dfc0 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
1dfd0 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
1dfe0 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
1dff0 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
1e000 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
1e010 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
1e020 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
1e030 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
1e040 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
1e050 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
1e060 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
1e070 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
1e080 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
1e090 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
1e0a0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1e0b0 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
1e0c0 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77  . .** ^On window
1e0d0 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
1e0e0 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
1e0f0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
1e100 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
1e110 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
1e120 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  :")..**.** [[cor
1e130 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
1e140 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
1e150 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
1e160 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
1e170 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
1e180 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
1e190 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
1e1a0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
1e1b0 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
1e1c0 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
1e1d0 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
1e1e0 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
1e1f0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
1e200 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d  hree query param
1e210 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
1e220 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
1e230 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
1e240 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
1e250 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
1e260 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
1e270 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
1e280 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
1e290 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
1e2a0 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
1e2b0 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
1e2c0 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
1e2d0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1e2e0 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
1e2f0 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
1e300 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
1e310 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
1e320 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
1e330 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
1e340 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
1e350 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
1e360 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
1e370 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
1e380 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
1e390 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
1e3a0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
1e3b0 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
1e3c0 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
1e3d0 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
1e3e0 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
1e3f0 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
1e400 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
1e410 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1e420 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1e430 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
1e440 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
1e450 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
1e460 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
1e470 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
1e480 22 72 77 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  "rw" or.**     "
1e490 72 77 63 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  rwc". Attempting
1e4a0 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
1e4b0 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
1e4c0 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
1e4d0 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
1e4e0 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
1e4f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1e500 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1e510 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
1e520 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
1e530 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1e540 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
1e550 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
1e560 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
1e570 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
1e580 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e590 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
1e5a0 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
1e5b0 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
1e5c0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1e5d0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1e5e0 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
1e5f0 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
1e600 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
1e610 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
1e620 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
1e630 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
1e640 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
1e650 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
1e660 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
1e670 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
1e680 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
1e690 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1e6a0 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
1e6b0 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 5e 49 66  OPEN_CREATE. ^If
1e6c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1e6d0 28 29 20 69 73 20 0a 2a 2a 20 20 20 20 20 75 73  () is .**     us
1e6e0 65 64 2c 20 69 74 20 69 73 20 61 6e 20 65 72 72  ed, it is an err
1e6f0 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
1e700 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 6d 6f  value for the mo
1e710 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
1e720 74 20 69 73 20 0a 2a 2a 20 20 20 20 20 6c 65 73  t is .**     les
1e730 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
1e740 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
1e750 64 20 62 79 20 74 68 65 20 66 6c 61 67 73 20 70  d by the flags p
1e760 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
1e770 72 64 20 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  rd .**     param
1e780 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  eter..**.**   <l
1e790 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
1e7a0 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
1e7b0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
1e7c0 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
1e7d0 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
1e7e0 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
1e7f0 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
1e800 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
1e810 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
1e820 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
1e830 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
1e840 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
1e850 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
1e860 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
1e870 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
1e880 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
1e890 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
1e8a0 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
1e8b0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
1e8c0 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
1e8d0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1e8e0 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
1e8f0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
1e900 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
1e910 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
1e920 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
1e930 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
1e940 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
1e950 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
1e960 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72 65  any behaviour re
1e970 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
1e980 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
1e990 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1e9a0 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
1e9b0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
1e9c0 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  ag..** </ul>.**.
1e9d0 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
1e9e0 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
1e9f0 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
1ea00 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
1ea10 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
1ea20 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
1ea30 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1ea40 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
1ea50 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
1ea60 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
1ea70 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
1ea80 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
1ea90 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
1eaa0 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
1eab0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
1eac0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1ead0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
1eae0 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
1eaf0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
1eb00 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
1eb10 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
1eb20 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
1eb30 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
1eb40 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
1eb50 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
1eb60 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
1eb70 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
1eb80 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
1eb90 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
1eba0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
1ebb0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
1ebc0 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
1ebd0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
1ebe0 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
1ebf0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
1ec00 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
1ec10 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
1ec20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
1ec30 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
1ec40 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
1ec50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
1ec60 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
1ec70 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
1ec80 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
1ec90 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
1eca0 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
1ecb0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
1ecc0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
1ecd0 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
1ece0 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
1ecf0 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
1ed00 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
1ed10 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
1ed20 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
1ed30 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
1ed40 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
1ed50 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
1ed60 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
1ed70 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
1ed80 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
1ed90 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
1eda0 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
1edb0 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
1edc0 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
1edd0 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
1ede0 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
1edf0 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
1ee00 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
1ee10 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
1ee20 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
1ee30 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
1ee40 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
1ee50 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
1ee60 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
1ee70 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
1ee80 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
1ee90 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
1eea0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
1eeb0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
1eec0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
1eed0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
1eee0 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
1eef0 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
1ef00 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1ef10 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
1ef20 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
1ef30 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
1ef40 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
1ef50 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
1ef60 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
1ef70 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
1ef80 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74  s=unix-nolock <t
1ef90 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
1efa0 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
1efb0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
1efc0 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
1efd0 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22  FS "unix-nolock"
1efe0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1eff0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
1f000 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
1f010 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
1f020 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
1f030 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
1f040 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
1f050 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
1f060 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
1f070 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
1f080 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
1f090 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
1f0a0 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
1f0b0 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
1f0c0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
1f0d0 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
1f0e0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
1f0f0 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
1f100 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
1f110 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
1f120 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
1f130 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
1f140 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
1f150 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
1f160 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
1f170 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
1f180 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
1f190 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
1f1a0 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
1f1b0 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
1f1c0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
1f1d0 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
1f1e0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
1f1f0 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
1f200 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
1f210 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
1f220 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
1f230 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
1f240 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
1f250 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
1f260 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
1f270 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
1f280 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
1f290 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
1f2a0 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
1f2b0 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
1f2c0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
1f2d0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
1f2e0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
1f2f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1f300 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
1f310 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
1f320 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
1f330 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
1f340 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
1f350 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
1f360 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
1f370 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
1f380 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
1f390 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
1f3a0 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
1f3b0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1f3c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1f3d0 5f 76 32 28 29 2e 0a 2a 2f 0a 53 51 4c 49 54 45  _v2()..*/.SQLITE
1f3e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1f3f0 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
1f400 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1f410 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1f420 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1f430 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1f440 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
1f450 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1f460 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  dle */.);.SQLITE
1f470 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1f480 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
1f490 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
1f4a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1f4b0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
1f4c0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1f4d0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1f4e0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1f4f0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c  handle */.);.SQL
1f500 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1f510 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
1f520 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
1f530 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1f540 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1f550 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
1f560 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
1f570 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1f580 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
1f590 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
1f5a0 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
1f5b0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1f5c0 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
1f5d0 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
1f5e0 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
1f5f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f600 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46   Obtain Values F
1f610 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72  or URI Parameter
1f620 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  s.**.** This is 
1f630 61 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e  a utility routin
1f640 65 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  e, useful to VFS
1f650 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
1f660 2c 20 74 68 61 74 20 63 68 65 63 6b 73 0a 2a 2a  , that checks.**
1f670 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74   to see if a dat
1f680 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61  abase file was a
1f690 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69   URI that contai
1f6a0 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71  ned a specific q
1f6b0 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74  uery .** paramet
1f6c0 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62  er, and if so ob
1f6d0 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20  tains the value 
1f6e0 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
1f6f0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
1f700 65 20 7a 46 69 6c 65 6e 61 6d 65 20 61 72 67 75  e zFilename argu
1f710 6d 65 6e 74 20 69 73 20 74 68 65 20 66 69 6c 65  ment is the file
1f720 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
1f730 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
1f740 65 6e 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  en().** method o
1f750 66 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  f a VFS implemen
1f760 74 61 74 69 6f 6e 2e 20 20 54 68 65 20 7a 50 61  tation.  The zPa
1f770 72 61 6d 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ram argument is 
1f780 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
1f790 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
1f7a0 65 72 20 77 65 20 73 65 65 6b 2e 20 20 54 68 69  er we seek.  Thi
1f7b0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
1f7c0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
1f7d0 68 65 20 7a 50 61 72 61 6d 0a 2a 2a 20 70 61 72  he zParam.** par
1f7e0 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
1f7f0 73 74 73 2e 20 20 49 66 20 74 68 65 20 70 61 72  sts.  If the par
1f800 61 6d 65 74 65 72 20 64 6f 65 73 20 6e 6f 74 20  ameter does not 
1f810 65 78 69 73 74 2c 20 74 68 69 73 20 72 6f 75 74  exist, this rout
1f820 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  ine.** returns a
1f830 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1f840 2a 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  *.** If the zFil
1f850 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74  ename argument t
1f860 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
1f870 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
1f880 20 74 68 61 74 20 53 51 4c 69 74 65 0a 2a 2a 20   that SQLite.** 
1f890 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
1f8a0 78 4f 70 65 6e 20 56 46 53 20 6d 65 74 68 6f 64  xOpen VFS method
1f8b0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1f8c0 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
1f8d0 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ine.** is undefi
1f8e0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
1f8f0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
1f900 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
1f910 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1f920 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
1f930 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
1f940 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
1f950 2a 7a 50 61 72 61 6d 29 3b 0a 0a 0a 2f 2a 0a 2a  *zParam);.../*.*
1f960 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1f970 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1f980 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
1f990 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1f9a0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1f9b0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
1f9c0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1f9d0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1f9e0 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
1f9f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
1fa00 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
1fa10 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
1fa20 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
1fa30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1fa40 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
1fa50 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
1fa60 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
1fa70 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
1fa80 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
1fa90 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1faa0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
1fab0 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
1fac0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1fad0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1fae0 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
1faf0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
1fb00 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
1fb10 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1fb20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1fb30 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
1fb40 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
1fb50 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
1fb60 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
1fb70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1fb80 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1fb90 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1fba0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1fbb0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1fbc0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1fbd0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1fbe0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1fbf0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1fc00 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
1fc10 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
1fc20 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
1fc30 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
1fc40 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
1fc50 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
1fc60 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
1fc70 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
1fc80 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
1fc90 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
1fca0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
1fcb0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
1fcc0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
1fcd0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1fce0 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
1fcf0 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1fd00 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68  ions.)^.**.** Wh
1fd10 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
1fd20 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1fd30 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
1fd40 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
1fd50 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
1fd60 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
1fd70 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
1fd80 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
1fd90 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
1fda0 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
1fdb0 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
1fdc0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
1fdd0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
1fde0 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
1fdf0 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
1fe00 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
1fe10 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
1fe20 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
1fe30 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1fe40 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
1fe50 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
1fe60 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
1fe70 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
1fe80 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
1fe90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1fea0 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
1feb0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
1fec0 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
1fed0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
1fee0 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
1fef0 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
1ff00 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
1ff10 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
1ff20 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
1ff30 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
1ff40 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
1ff50 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
1ff60 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
1ff70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
1ff80 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
1ff90 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
1ffa0 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
1ffb0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
1ffc0 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
1ffd0 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
1ffe0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
1fff0 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
20000 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
20010 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
20020 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
20030 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
20040 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
20050 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
20060 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
20070 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
20080 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
20090 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
200a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
200b0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
200c0 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
200d0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
200e0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
200f0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
20100 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
20110 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
20120 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
20130 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20140 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
20150 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
20160 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
20170 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
20180 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
20190 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
201a0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
201b0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
201c0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
201d0 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
201e0 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
201f0 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
20200 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
20210 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
20220 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
20230 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
20240 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
20250 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
20260 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
20270 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
20280 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20290 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
202a0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
202b0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
202c0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
202d0 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
202e0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
202f0 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
20300 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
20310 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
20320 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
20330 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
20340 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
20350 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
20360 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
20370 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
20380 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
20390 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
203a0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
203b0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
203c0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
203d0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
203e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
203f0 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
20400 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
20410 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
20420 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
20430 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
20440 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
20450 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
20460 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
20470 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
20480 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
20490 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
204a0 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
204b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
204c0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
204d0 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
204e0 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
204f0 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
20500 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
20510 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
20520 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
20530 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
20540 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
20550 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
20560 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
20570 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
20580 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
20590 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
205a0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
205b0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
205c0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
205d0 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
205e0 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
205f0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
20600 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
20610 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
20620 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
20630 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
20640 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
20650 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
20660 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
20670 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
20680 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
20690 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
206a0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
206b0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
206c0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
206d0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
206e0 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
206f0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
20700 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
20710 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
20720 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
20730 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
20740 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
20750 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
20760 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
20770 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
20780 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
20790 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
207a0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
207b0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
207c0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
207d0 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
207e0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
207f0 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
20800 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
20810 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
20820 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
20830 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
20840 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
20850 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
20860 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
20870 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
20880 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
20890 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
208a0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
208b0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
208c0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
208d0 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
208e0 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
208f0 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
20900 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
20910 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
20920 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
20930 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
20940 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
20950 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
20960 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
20970 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
20980 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
20990 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
209a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
209b0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
209c0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
209d0 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
209e0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
209f0 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
20a00 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
20a10 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
20a20 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
20a30 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
20a40 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
20a50 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
20a60 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
20a70 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
20a80 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
20a90 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
20aa0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
20ab0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
20ac0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
20ad0 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
20ae0 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
20af0 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
20b00 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
20b10 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
20b20 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
20b30 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
20b40 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20b50 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
20b60 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
20b70 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
20b80 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
20b90 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
20ba0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
20bb0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
20bc0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
20bd0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
20be0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
20bf0 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
20c00 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
20c10 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
20c20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
20c30 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
20c40 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
20c50 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
20c60 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
20c70 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
20c80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20c90 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
20ca0 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
20cb0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
20cc0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
20cd0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
20ce0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
20cf0 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
20d00 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
20d10 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
20d20 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
20d30 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
20d40 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
20d50 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
20d60 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
20d70 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
20d80 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
20d90 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
20da0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
20db0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
20dc0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
20dd0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
20de0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
20df0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
20e00 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
20e10 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
20e20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20e30 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
20e40 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
20e50 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
20e60 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
20e70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
20e80 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
20e90 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
20ea0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
20eb0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
20ec0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
20ed0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
20ee0 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
20ef0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
20f00 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
20f10 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
20f20 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
20f30 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
20f40 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
20f50 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
20f60 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
20f70 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
20f80 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
20f90 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
20fa0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
20fb0 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
20fc0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
20fd0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
20fe0 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
20ff0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
21000 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
21010 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
21020 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
21030 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
21040 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
21050 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
21060 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
21070 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
21080 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
21090 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
210a0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
210b0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
210c0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
210d0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
210e0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
210f0 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
21100 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
21110 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
21120 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
21130 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
21140 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
21150 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
21160 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
21170 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
21180 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
21190 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
211a0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
211b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
211c0 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
211d0 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
211e0 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
211f0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
21200 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
21210 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
21220 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
21230 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
21240 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
21250 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
21260 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
21270 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
21280 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
21290 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
212a0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
212b0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
212c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
212d0 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
212e0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
212f0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
21300 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
21310 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
21320 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
21330 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
21340 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
21350 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
21360 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
21370 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
21380 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
21390 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
213a0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
213b0 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
213c0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
213d0 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
213e0 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
213f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
21400 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
21410 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
21420 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
21430 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
21440 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
21450 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
21460 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
21470 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
21480 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
21490 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
214a0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
214b0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
214c0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
214d0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
214e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
214f0 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
21500 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
21510 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
21520 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21530 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
21540 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21550 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
21560 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
21570 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
21580 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
21590 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
215a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
215b0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
215c0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
215d0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
215e0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
215f0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
21600 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
21610 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
21620 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
21630 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
21640 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
21650 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
21660 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
21670 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
21680 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
21690 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
216a0 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
216b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
216c0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
216d0 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
216e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
216f0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
21700 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
21710 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
21720 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
21730 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a           10../*.
21740 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
21750 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
21760 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
21770 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
21780 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
21790 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
217a0 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
217b0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
217c0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
217d0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
217e0 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
217f0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
21800 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
21810 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
21820 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
21830 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
21840 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
21850 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
21860 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
21870 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
21880 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
21890 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
218a0 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
218b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
218c0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
218d0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
218e0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
218f0 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
21900 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
21910 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
21920 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
21930 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
21940 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
21950 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
21960 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21970 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
21980 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
21990 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
219a0 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
219b0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
219c0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
219d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
219e0 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
219f0 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
21a00 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
21a10 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
21a20 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
21a30 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
21a40 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
21a50 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
21a60 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
21a70 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
21a80 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68   from zSql.  ^Wh
21a90 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
21aa0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
21ab0 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
21ac0 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
21ad0 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
21ae0 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
21af0 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
21b00 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
21b10 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
21b20 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
21b30 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
21b40 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
21b50 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
21b60 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
21b70 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
21b80 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
21b90 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
21ba0 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
21bb0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
21bc0 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
21bd0 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
21be0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
21bf0 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
21c00 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
21c10 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
21c20 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73  or bytes as this
21c30 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72   saves SQLite fr
21c40 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20  om having to.** 
21c50 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
21c60 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
21c70 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
21c80 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
21c90 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
21ca0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
21cb0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
21cc0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
21cd0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
21ce0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
21cf0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
21d00 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
21d10 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
21d20 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
21d30 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
21d40 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
21d50 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
21d60 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
21d70 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
21d80 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
21d90 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
21da0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
21db0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
21dc0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
21dd0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
21de0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
21df0 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
21e00 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
21e10 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
21e20 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
21e30 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
21e40 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
21e50 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
21e60 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
21e70 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
21e80 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
21e90 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
21ea0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
21eb0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
21ec0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
21ed0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
21ee0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
21ef0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
21f00 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
21f10 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
21f20 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
21f30 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
21f40 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
21f50 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
21f60 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
21f70 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
21f80 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
21f90 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
21fa0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
21fb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21fc0 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
21fd0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
21fe0 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
21ff0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
22000 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
22010 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
22020 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
22030 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
22040 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
22050 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
22060 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
22070 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
22080 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
22090 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
220a0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
220b0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
220c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
220d0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
220e0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
220f0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
22100 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
22110 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
22120 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
22130 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
22140 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
22150 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
22160 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
22170 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
22180 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
22190 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
221a0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
221b0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
221c0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
221d0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
221e0 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
221f0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
22200 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
22210 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
22220 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a  run it again..**
22230 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
22240 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
22250 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
22260 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
22270 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
22280 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
22290 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
222a0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
222b0 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
222c0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
222d0 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
222e0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
222f0 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
22300 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
22310 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
22320 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
22330 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
22340 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
22350 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
22360 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
22370 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
22380 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
22390 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
223a0 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
223b0 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
223c0 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
223d0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
223e0 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
223f0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
22400 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
22410 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
22420 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
22430 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
22440 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
22450 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
22460 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
22470 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
22480 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
22490 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
224a0 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
224b0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
224c0 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
224d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
224e0 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
224f0 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
22500 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
22510 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
22520 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22530 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
22540 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
22550 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
22560 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
22570 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
22580 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
22590 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
225a0 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
225b0 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
225c0 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
225d0 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
225e0 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
225f0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
22600 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
22610 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
22620 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
22630 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
22640 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
22650 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
22660 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
22670 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
22680 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
22690 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
226a0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65   enabled..** the
226b0 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f   .** </li>.** </
226c0 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ol>.*/.SQLITE_AP
226d0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
226e0 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
226f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
22700 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
22710 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
22720 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
22730 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
22740 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
22750 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
22760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
22770 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
22780 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
22790 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
227a0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
227b0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
227c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
227d0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
227e0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
227f0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
22800 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
22810 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
22820 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
22830 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
22840 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
22850 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
22860 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
22870 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
22880 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
22890 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
228a0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
228b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
228c0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
228d0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
228e0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
228f0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
22900 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
22910 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
22920 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
22930 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
22940 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
22950 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
22960 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
22970 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
22980 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
22990 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
229a0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
229b0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
229c0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
229d0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
229e0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
229f0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
22a00 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
22a10 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
22a20 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
22a30 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
22a40 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
22a50 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
22a60 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
22a70 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
22a80 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
22a90 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
22aa0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
22ab0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
22ac0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
22ad0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
22ae0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
22af0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
22b00 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
22b10 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
22b20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
22b30 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
22b40 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
22b50 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
22b60 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
22b70 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
22b80 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
22b90 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
22ba0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
22bb0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
22bc0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
22bd0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
22be0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
22bf0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
22c00 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
22c10 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
22c20 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
22c30 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
22c40 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
22c50 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
22c60 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
22c70 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
22c80 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
22c90 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
22ca0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22cb0 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
22cc0 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
22cd0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
22ce0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22cf0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
22d00 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
22d10 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
22d20 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
22d30 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
22d40 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
22d50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22d60 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
22d70 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
22d80 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
22d90 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ase.**.** ^The s
22da0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
22db0 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
22dc0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
22dd0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
22de0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
22df0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22e00 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
22e10 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
22e20 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
22e30 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
22e40 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
22e50 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
22e60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
22e70 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
22e80 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
22e90 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
22ea0 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
22eb0 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
22ec0 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
22ed0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
22ee0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
22ef0 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
22f00 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
22f10 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
22f20 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
22f30 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
22f40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
22f50 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
22f60 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
22f70 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
22f80 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
22f90 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
22fa0 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
22fb0 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
22fc0 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
22fd0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
22fe0 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
22ff0 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
23000 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
23010 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
23020 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
23030 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
23040 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
23050 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
23060 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
23070 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
23080 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
23090 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
230a0 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
230b0 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
230c0 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
230d0 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
230e0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
230f0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
23100 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
23110 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
23120 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
23130 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
23140 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
23150 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
23160 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
23170 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
23180 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
23190 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
231a0 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
231b0 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
231c0 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
231d0 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
231e0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
231f0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
23200 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
23210 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
23220 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
23230 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
23240 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23250 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
23260 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
23270 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
23280 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
23290 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
232a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
232b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
232c0 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
232d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
232e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
232f0 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
23300 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
23310 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
23320 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
23330 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
23340 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
23350 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
23360 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
23370 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
23380 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
23390 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
233a0 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
233b0 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
233c0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
233d0 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
233e0 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
233f0 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
23400 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
23410 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
23420 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
23430 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
23440 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
23450 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
23460 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
23470 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
23480 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
23490 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
234a0 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
234b0 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
234c0 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
234d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
234e0 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
234f0 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
23500 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
23510 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
23520 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
23530 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
23540 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
23550 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
23560 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
23570 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
23580 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
23590 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
235a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
235b0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
235c0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
235d0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
235e0 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
235f0 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
23600 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
23610 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
23620 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
23630 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
23640 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
23650 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
23660 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
23670 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
23680 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
23690 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
236a0 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
236b0 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
236c0 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
236d0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
236e0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
236f0 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
23700 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
23710 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
23720 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
23730 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
23740 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
23750 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
23760 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
23770 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
23780 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
23790 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
237a0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
237b0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
237c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
237d0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
237e0 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
237f0 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
23800 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
23810 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
23820 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
23830 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
23840 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
23850 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
23860 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
23870 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
23880 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
23890 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
238a0 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
238b0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
238c0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
238d0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
238e0 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
238f0 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
23900 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
23910 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
23920 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
23930 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
23940 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
23950 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
23960 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
23970 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
23980 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
23990 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
239a0 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
239b0 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
239c0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
239d0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
239e0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
239f0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
23a00 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
23a10 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
23a20 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
23a30 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
23a40 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
23a50 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
23a60 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
23a70 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
23a80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
23a90 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
23aa0 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
23ab0 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
23ac0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
23ad0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
23ae0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
23af0 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
23b00 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
23b10 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
23b20 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
23b30 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
23b40 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
23b50 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
23b60 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
23b70 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
23b80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
23b90 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
23ba0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
23bb0 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
23bc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
23bd0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
23be0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
23bf0 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
23c00 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
23c10 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
23c20 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
23c30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
23c40 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
23c50 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
23c60 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
23c70 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
23c80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
23c90 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
23ca0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
23cb0 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
23cc0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
23cd0 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
23ce0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
23cf0 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
23d00 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
23d10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
23d20 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
23d30 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
23d40 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
23d50 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
23d60 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
23d70 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
23d80 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
23d90 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
23da0 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
23db0 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
23dc0 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
23dd0 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
23de0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
23df0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
23e00 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
23e10 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
23e20 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
23e30 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
23e40 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
23e50 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
23e60 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
23e70 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
23e80 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
23e90 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
23ea0 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
23eb0 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
23ec0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
23ed0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
23ee0 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
23ef0 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
23f00 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
23f10 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
23f20 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
23f30 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
23f40 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
23f50 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
23f60 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
23f70 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
23f80 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
23f90 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
23fa0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
23fb0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
23fc0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
23fd0 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
23fe0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
23ff0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
24000 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
24010 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
24020 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
24030 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
24040 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
24050 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
24060 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
24070 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
24080 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
24090 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
240a0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
240b0 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
240c0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
240d0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
240e0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
240f0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
24100 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
24110 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
24120 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
24130 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
24140 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
24150 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
24160 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
24170 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
24180 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
24190 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
241a0 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
241b0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
241c0 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
241d0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
241e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
241f0 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
24200 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
24210 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
24220 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
24230 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
24240 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
24250 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
24260 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
24270 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
24280 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
24290 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
242a0 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
242b0 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
242c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
242d0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
242e0 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
242f0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
24300 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
24310 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
24320 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
24330 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
24340 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
24350 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
24360 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
24370 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
24380 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
24390 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
243a0 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
243b0 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
243c0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
243d0 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
243e0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
243f0 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
24400 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
24410 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
24420 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
24430 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
24440 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
24450 72 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  r..** If a non-n
24460 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
24470 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
24480 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
24490 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
244a0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
244b0 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61  ext16() then tha
244c0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
244d0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
244e0 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
244f0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
24500 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
24510 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
24520 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
24530 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
24540 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
24550 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
24560 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
24570 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
24580 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
24590 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
245a0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
245b0 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
245c0 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
245d0 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
245e0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
245f0 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
24600 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
24610 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
24620 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
24630 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
24640 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
24650 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
24660 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
24670 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
24680 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
24690 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
246a0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
246b0 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
246c0 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
246d0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
246e0 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
246f0 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
24700 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
24710 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
24720 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
24730 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
24740 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20  bind_blob(),.** 
24750 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
24760 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  t(), or sqlite3_
24770 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61  bind_text16() fa
24780 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68  ils.  .** ^If th
24790 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
247a0 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
247b0 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
247c0 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
247d0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
247e0 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
247f0 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
24800 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
24810 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
24820 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
24830 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
24840 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
24850 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
24860 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
24870 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
24880 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
24890 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
248a0 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
248b0 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
248c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
248d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
248e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
248f0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
24900 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
24910 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
24920 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
24930 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
24940 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
24950 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
24960 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
24970 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
24980 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
24990 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
249a0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
249b0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
249c0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
249d0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
249e0 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
249f0 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
24a00 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
24a10 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
24a20 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
24a30 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
24a40 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
24a50 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
24a60 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
24a70 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
24a80 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
24a90 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
24aa0 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
24ab0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
24ac0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
24ad0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
24ae0 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
24af0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24b00 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
24b10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
24b20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
24b30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
24b40 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
24b50 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
24b60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24b70 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
24b80 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
24b90 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
24ba0 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
24bb0 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
24bc0 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
24bd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24be0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
24bf0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
24c00 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
24c10 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
24c20 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
24c30 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
24c40 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
24c50 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
24c60 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
24c70 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
24c80 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
24c90 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
24ca0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
24cb0 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
24cc0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
24cd0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
24ce0 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
24cf0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
24d00 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
24d10 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
24d20 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
24d30 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
24d40 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
24d50 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
24d60 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
24d70 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
24d80 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
24d90 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
24da0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
24db0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
24dc0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
24dd0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
24de0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
24df0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
24e00 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
24e10 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
24e20 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
24e30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
24e40 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
24e50 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
24e60 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
24e70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
24e80 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
24e90 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
24ea0 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  e);.SQLITE_API i
24eb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
24ec0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
24ed0 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51  *, int, int);.SQ
24ee0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
24ef0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
24f00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
24f10 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
24f20 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  4);.SQLITE_API i
24f30 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
24f40 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
24f50 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
24f60 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
24f70 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
24f80 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
24f90 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
24fa0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
24fb0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
24fc0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
24fd0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
24fe0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
24ff0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
25000 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
25010 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
25020 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
25030 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
25040 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
25050 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
25060 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
25070 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
25080 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
25090 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
250a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
250b0 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
250c0 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
250d0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
250e0 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
250f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
25100 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
25110 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
25120 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
25130 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
25140 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
25150 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
25160 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
25170 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
25180 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
25190 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
251a0 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
251b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
251c0 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
251d0 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
251e0 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
251f0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
25200 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
25210 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
25220 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
25230 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
25240 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
25250 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
25260 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
25270 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
25280 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
25290 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
252a0 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
252b0 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
252c0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
252d0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
252e0 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
252f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
25300 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25310 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
25320 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
25330 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
25340 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
25350 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25360 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
25370 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
25380 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
25390 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
253a0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
253b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
253c0 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
253d0 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
253e0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
253f0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
25400 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
25410 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
25420 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
25430 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
25440 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25450 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
25460 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
25470 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
25480 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
25490 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
254a0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
254b0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
254c0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
254d0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
254e0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
254f0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
25500 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
25510 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
25520 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
25530 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
25540 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
25550 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
25560 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
25570 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
25580 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
25590 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
255a0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
255b0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
255c0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
255d0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
255e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
255f0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
25600 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
25610 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
25620 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
25630 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
25640 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
25650 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
25660 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
25670 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
25680 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
25690 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
256a0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
256b0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
256c0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
256d0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
256e0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
256f0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
25700 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
25710 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
25720 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
25730 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
25740 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
25750 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
25760 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
25770 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25780 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
25790 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
257a0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
257b0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
257c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
257d0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
257e0 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
257f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
25800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
25810 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
25820 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
25830 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   Name.**.** ^Ret
25840 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
25850 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
25860 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
25870 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
25880 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
25890 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
258a0 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
258b0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
258c0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
258d0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
258e0 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
258f0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
25900 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
25910 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
25920 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
25930 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
25940 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
25950 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
25960 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
25970 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
25980 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
25990 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
259a0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
259b0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
259c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
259d0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
259e0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
259f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
25a00 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
25a10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
25a20 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
25a30 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
25a40 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
25a50 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
25a60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25a70 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
25a80 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
25a90 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
25aa0 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
25ab0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
25ac0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
25ad0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
25ae0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
25af0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
25b00 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
25b10 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
25b20 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
25b30 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
25b40 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
25b50 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
25b60 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
25b70 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
25b80 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45   NULL..*/.SQLITE
25b90 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
25ba0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
25bb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
25bc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25bd0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
25be0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
25bf0 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  et.**.** ^Return
25c00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
25c10 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
25c20 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
25c30 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
25c40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25c50 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
25c60 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
25c70 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
25c80 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
25c90 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
25ca0 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
25cb0 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
25cc0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
25cd0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
25ce0 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
25cf0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
25d00 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
25d10 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
25d20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25d30 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
25d40 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
25d50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
25d60 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
25d70 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
25d80 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
25d90 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
25da0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
25db0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
25dc0 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
25dd0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
25de0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
25df0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
25e00 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
25e10 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
25e20 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
25e30 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
25e40 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
25e50 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
25e60 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
25e70 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
25e80 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
25e90 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
25ea0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
25eb0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
25ec0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
25ed0 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
25ee0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
25ef0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
25f00 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
25f10 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
25f20 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
25f30 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
25f40 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
25f50 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
25f60 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
25f70 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
25f80 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
25f90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
25fa0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
25fb0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
25fc0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
25fd0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
25fe0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
25ff0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
26000 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
26010 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
26020 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
26030 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
26040 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
26050 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26060 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
26070 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
26080 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
26090 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
260a0 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
260b0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
260c0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
260d0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
260e0 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
260f0 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
26100 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
26110 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
26120 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
26130 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
26140 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
26150 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
26160 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
26170 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
26180 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
26190 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
261a0 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
261b0 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
261c0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
261d0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
261e0 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
261f0 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
26200 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
26210 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
26220 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
26230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26240 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26250 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
26260 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
26270 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
26280 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
26290 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
262a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
262b0 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
262c0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
262d0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
262e0 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
262f0 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
26300 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
26310 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
26320 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
26330 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
26340 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
26350 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
26360 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
26370 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
26380 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
26390 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
263a0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
263b0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
263c0 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
263d0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
263e0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
263f0 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
26400 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
26410 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
26420 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
26430 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
26440 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
26450 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
26460 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
26470 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
26480 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
26490 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
264a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
264b0 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
264c0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
264d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
264e0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
264f0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
26500 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
26510 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
26520 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
26530 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
26540 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
26550 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
26560 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
26570 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
26580 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
26590 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
265a0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
265b0 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
265c0 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
265d0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
265e0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
265f0 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
26600 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
26610 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
26620 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
26630 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
26640 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
26650 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
26660 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
26670 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
26680 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
26690 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
266a0 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
266b0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
266c0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
266d0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
266e0 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
266f0 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
26700 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
26710 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
26720 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
26730 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
26740 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
26750 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
26760 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
26770 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
26780 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
26790 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
267a0 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
267b0 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
267c0 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
267d0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
267e0 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
267f0 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
26800 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
26810 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
26820 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
26830 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
26840 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
26850 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
26860 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
26870 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
26880 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
26890 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
268a0 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
268b0 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
268c0 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
268d0 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
268e0 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
268f0 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
26900 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
26910 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
26920 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
26930 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
26940 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
26950 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
26960 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
26970 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
26980 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
26990 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
269a0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
269b0 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
269c0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
269d0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
269e0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
269f0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
26a00 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
26a10 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
26a20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
26a30 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
26a40 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
26a50 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
26a60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
26a70 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
26a80 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
26a90 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
26aa0 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
26ab0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
26ac0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
26ad0 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
26ae0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
26af0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
26b00 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
26b10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
26b20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
26b30 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
26b40 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
26b50 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
26b60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
26b70 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
26b80 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
26b90 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
26ba0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
26bb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
26bc0 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
26bd0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
26be0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
26bf0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
26c00 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
26c10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
26c20 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
26c30 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
26c40 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
26c50 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
26c60 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
26c70 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
26c80 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
26c90 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
26ca0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
26cb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26cc0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
26cd0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
26ce0 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
26cf0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
26d00 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
26d10 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
26d20 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
26d30 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
26d40 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
26d50 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
26d60 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
26d70 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
26d80 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
26d90 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
26da0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
26db0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
26dc0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
26dd0 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
26de0 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
26df0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
26e00 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
26e10 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
26e20 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
26e30 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
26e40 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
26e50 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
26e60 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
26e70 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
26e80 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
26e90 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
26ea0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
26eb0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
26ec0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
26ed0 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
26ee0 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
26ef0 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
26f00 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
26f10 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
26f20 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
26f30 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
26f40 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
26f50 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
26f60 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
26f70 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
26f80 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
26f90 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
26fa0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
26fb0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
26fc0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
26fd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
26fe0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
26ff0 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
27000 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
27010 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
27020 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
27030 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
27040 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
27050 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
27060 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
27070 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
27080 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
27090 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
270a0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
270b0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
270c0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
270d0 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
270e0 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
270f0 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
27100 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
27110 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
27120 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
27130 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
27140 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
27150 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27160 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
27170 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
27180 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
27190 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
271a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
271b0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
271c0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
271d0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
271e0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
271f0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
27200 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
27210 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
27220 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
27230 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
27240 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
27250 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
27260 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
27270 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
27280 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
27290 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
272a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
272b0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
272c0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
272d0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
272e0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
272f0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
27300 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
27310 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
27320 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
27330 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
27340 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
27350 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
27360 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
27370 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
27380 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
27390 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
273a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
273b0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
273c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
273d0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
273e0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
273f0 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
27400 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
27410 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
27420 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
27430 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
27440 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
27450 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
27460 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
27470 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
27480 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
27490 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
274a0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
274b0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
274c0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
274d0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
274e0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
274f0 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
27500 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
27510 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
27520 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
27530 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
27540 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
27550 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
27560 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
27570 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
27580 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
27590 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
275a0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
275b0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
275c0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
275d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
275e0 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
275f0 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
27600 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
27610 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
27620 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
27630 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
27640 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
27650 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
27660 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
27670 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
27680 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
27690 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
276a0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
276b0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
276c0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
276d0 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
276e0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
276f0 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
27700 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
27710 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
27720 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
27730 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
27740 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
27750 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
27760 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
27770 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
27780 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
27790 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
277a0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
277b0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
277c0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
277d0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
277e0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
277f0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
27800 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
27810 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
27820 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
27830 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
27840 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
27850 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
27860 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
27870 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
27880 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
27890 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
278a0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
278b0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
278c0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
278d0 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
278e0 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
278f0 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
27900 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
27910 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
27920 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
27930 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
27940 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
27950 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
27960 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
27970 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
27980 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
27990 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
279a0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
279b0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
279c0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
279d0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
279e0 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
279f0 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
27a00 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
27a10 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
27a20 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
27a30 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
27a40 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
27a50 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
27a60 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
27a70 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
27a80 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
27a90 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
27aa0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
27ab0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
27ac0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
27ad0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
27ae0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27af0 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
27b00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
27b10 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
27b20 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
27b30 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
27b40 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
27b50 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
27b60 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
27b70 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
27b80 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
27b90 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
27ba0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
27bb0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
27bc0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
27bd0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
27be0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27bf0 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
27c00 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
27c10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
27c20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
27c30 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
27c40 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
27c50 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
27c60 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
27c70 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
27c80 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
27c90 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
27ca0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27cb0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
27cc0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
27cd0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
27ce0 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
27cf0 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
27d00 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
27d10 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
27d20 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
27d30 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
27d40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
27d50 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
27d60 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
27d70 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
27d80 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
27d90 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
27da0 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
27db0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
27dc0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
27dd0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
27de0 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
27df0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
27e00 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
27e10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27e20 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
27e30 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
27e40 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
27e50 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
27e60 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
27e70 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
27e80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
27e90 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
27ea0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27eb0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
27ec0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
27ed0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
27ee0 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
27ef0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
27f00 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
27f10 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
27f20 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
27f30 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
27f40 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
27f50 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
27f60 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
27f70 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
27f80 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
27f90 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
27fa0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
27fb0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
27fc0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
27fd0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
27fe0 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
27ff0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
28000 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
28010 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
28020 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
28030 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
28040 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
28050 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
28060 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
28070 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
28080 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
28090 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
280a0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
280b0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
280c0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
280d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
280e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
280f0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
28100 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
28110 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
28120 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
28130 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
28140 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
28150 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
28160 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
28170 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
28180 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
28190 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
281a0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
281b0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
281c0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
281d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
281e0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
281f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28200 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
28210 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
28220 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
28230 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
28240 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
28250 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
28260 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
28270 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
28280 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
28290 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
282a0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
282b0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
282c0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
282d0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
282e0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
282f0 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ended..*/.SQLITE
28300 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
28310 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
28320 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
28330 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
28340 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
28350 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
28360 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
28370 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
28380 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
28390 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
283a0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
283b0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
283c0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
283d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
283e0 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
283f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
28400 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
28410 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
28420 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
28430 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
28440 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
28450 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
28460 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
28470 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
28480 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
28490 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
284a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
284b0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
284c0 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
284d0 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
284e0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
284f0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
28500 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
28510 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
28520 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
28530 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
28540 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
28550 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
28560 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
28570 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
28580 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
28590 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
285a0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
285b0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
285c0 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
285d0 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
285e0 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
285f0 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
28600 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
28610 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
28620 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
28630 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
28640 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
28650 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
28660 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
28670 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
28680 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
28690 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51  n_count()].*/.SQ
286a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
286b0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
286c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
286d0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
286e0 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
286f0 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
28700 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
28710 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
28720 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
28730 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
28740 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
28750 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
28760 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
28770 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
28780 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
28790 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
287a0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
287b0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
287c0 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
287d0 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
287e0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
287f0 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
28800 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
28810 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
28820 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
28830 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
28840 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
28850 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
28860 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
28870 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
28880 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
28890 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
288a0 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
288b0 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
288c0 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
288d0 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
288e0 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
288f0 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
28900 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
28910 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
28920 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
28930 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
28940 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
28950 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
28960 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
28970 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
28980 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
28990 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
289a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
289b0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
289c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
289d0 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
289e0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
289f0 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
28a00 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
28a10 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
28a20 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
28a30 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
28a40 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
28a50 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
28a60 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
28a70 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
28a80 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
28a90 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
28aa0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
28ab0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
28ac0 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
28ad0 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
28ae0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
28af0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
28b00 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
28b10 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
28b20 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
28b30 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
28b40 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
28b50 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
28b60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28b70 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
28b80 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
28b90 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
28ba0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
28bb0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
28bc0 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
28bd0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
28be0 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
28bf0 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
28c00 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
28c10 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
28c20 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
28c30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
28c40 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
28c50 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
28c60 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
28c70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
28c80 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
28c90 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
28ca0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
28cb0 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
28cc0 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
28cd0 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
28ce0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
28cf0 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
28d00 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
28d10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
28d20 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
28d30 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
28d40 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
28d50 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
28d60 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
28d70 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
28d80 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
28d90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28da0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
28db0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
28dc0 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
28dd0 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
28de0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
28df0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
28e00 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
28e10 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
28e20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28e30 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
28e40 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
28e50 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
28e60 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
28e70 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
28e80 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
28e90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
28ea0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
28eb0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
28ec0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
28ed0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
28ee0 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
28ef0 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
28f00 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
28f10 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
28f20 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
28f30 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
28f40 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
28f50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28f60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
28f70 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
28f80 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
28f90 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
28fa0 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
28fb0 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
28fc0 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
28fd0 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
28fe0 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
28ff0 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
29000 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
29010 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
29020 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
29030 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
29040 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
29050 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
29060 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
29070 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
29080 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
29090 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
290a0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
290b0 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
290c0 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
290d0 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
290e0 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
290f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
29100 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
29110 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
29120 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
29130 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
29140 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
29150 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
29160 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29170 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
29180 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
29190 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
291a0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
291b0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
291c0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
291d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
291e0 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
291f0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
29200 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
29210 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
29220 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
29230 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
29240 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
29250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29260 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
29270 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
29280 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
29290 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
292a0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
292b0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
292c0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
292d0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
292e0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
292f0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
29300 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
29310 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
29320 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
29330 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
29340 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
29350 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
29360 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
29370 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
29380 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
29390 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
293a0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
293b0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
293c0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
293d0 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
293e0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
293f0 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
29400 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
29410 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
29420 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
29430 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
29440 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
29450 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
29460 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
29470 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
29480 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
29490 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
294a0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
294b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
294c0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
294d0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
294e0 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
294f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29500 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
29510 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
29520 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
29530 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
29540 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
29550 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
29560 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
29570 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
29580 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
29590 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
295a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
295b0 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
295c0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
295d0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
295e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
295f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
29600 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
29610 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
29620 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
29630 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
29640 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
29650 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
29660 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
29670 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
29680 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
29690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
296a0 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
296b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
296c0 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
296d0 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
296e0 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
296f0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
29700 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
29710 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
29720 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
29730 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
29740 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29750 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
29760 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
29770 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
29780 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54   terminated.  ^T
29790 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
297a0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
297b0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
297c0 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
297d0 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
297e0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
297f0 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
29800 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
29810 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
29820 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
29830 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29840 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
29850 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
29860 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29870 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
29880 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
29890 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
298a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
298b0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
298c0 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
298d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
298e0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
298f0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
29900 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
29910 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
29920 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
29930 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
29940 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
29950 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
29960 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
29970 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
29980 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
29990 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
299a0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
299b0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
299c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
299d0 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
299e0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
299f0 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
29a00 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
29a10 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
29a20 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
29a30 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
29a40 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
29a50 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
29a60 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
29a70 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
29a80 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
29a90 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
29aa0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
29ab0 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
29ac0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
29ad0 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
29ae0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
29af0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
29b00 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
29b10 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
29b20 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
29b30 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
29b40 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
29b50 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
29b60 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
29b70 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
29b80 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
29b90 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
29ba0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
29bb0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
29bc0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
29bd0 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
29be0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
29bf0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
29c00 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
29c10 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
29c20 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
29c30 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
29c40 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
29c50 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
29c60 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
29c70 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
29c80 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
29c90 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
29ca0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
29cb0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
29cc0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
29cd0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
29ce0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
29cf0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
29d00 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
29d10 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
29d20 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
29d30 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
29d40 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
29d50 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
29d60 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
29d70 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
29d80 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
29d90 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
29da0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
29db0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
29dc0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
29dd0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
29de0 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
29df0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
29e00 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
29e10 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
29e20 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
29e30 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
29e40 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
29e50 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
29e60 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
29e70 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
29e80 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
29e90 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
29ea0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
29eb0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
29ec0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
29ed0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
29ee0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
29ef0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
29f00 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
29f10 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
29f20 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
29f30 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
29f40 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
29f50 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
29f60 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
29f70 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
29f80 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
29f90 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
29fa0 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
29fb0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
29fc0 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
29fd0 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
29fe0 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
29ff0 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
2a000 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
2a010 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
2a020 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
2a030 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
2a040 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
2a050 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
2a060 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
2a070 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
2a080 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
2a090 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
2a0a0 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
2a0b0 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
2a0c0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
2a0d0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
2a0e0 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
2a0f0 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
2a100 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2a110 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2a120 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
2a130 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
2a140 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2a150 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
2a160 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
2a170 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
2a180 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
2a190 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
2a1a0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
2a1b0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
2a1c0 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
2a1d0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2a1e0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
2a1f0 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
2a200 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2a210 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2a220 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2a230 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
2a240 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2a250 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
2a260 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
2a270 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
2a280 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2a290 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2a2a0 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
2a2b0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2a2c0 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
2a2d0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2a2e0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2a2f0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2a300 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2a310 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2a320 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
2a330 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2a340 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2a350 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
2a360 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a370 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
2a380 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a390 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
2a3a0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2a3b0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2a3c0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2a3d0 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
2a3e0 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
2a3f0 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2a400 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2a410 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2a420 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2a430 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2a440 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2a450 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2a460 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2a470 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2a480 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2a490 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
2a4a0 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
2a4b0 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
2a4c0 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
2a4d0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
2a4e0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
2a4f0 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
2a500 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
2a510 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
2a520 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
2a530 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
2a540 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
2a550 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
2a560 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
2a570 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
2a580 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
2a590 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
2a5a0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
2a5b0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
2a5c0 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
2a5d0 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
2a5e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a5f0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2a600 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a610 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2a620 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2a630 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
2a640 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2a650 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2a660 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2a670 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2a680 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2a690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2a6a0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
2a6b0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
2a6c0 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
2a6d0 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
2a6e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2a6f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2a700 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
2a710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2a720 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
2a730 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
2a740 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
2a750 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
2a760 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2a770 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2a780 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2a790 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
2a7a0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
2a7b0 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
2a7c0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
2a7d0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
2a7e0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
2a7f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2a800 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
2a810 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2a820 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
2a830 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
2a840 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2a850 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
2a860 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
2a870 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a880 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
2a890 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
2a8a0 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
2a8b0 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
2a8c0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
2a8d0 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
2a8e0 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
2a8f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2a900 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2a910 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2a920 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2a930 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
2a940 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
2a950 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
2a960 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
2a970 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
2a980 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
2a990 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
2a9a0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2a9b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
2a9c0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
2a9d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2a9e0 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
2a9f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2aa00 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
2aa10 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2aa20 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2aa30 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2aa40 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2aa50 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2aa60 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2aa70 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2aa80 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2aa90 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2aaa0 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2aab0 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2aac0 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2aad0 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2aae0 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2aaf0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2ab00 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2ab10 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2ab20 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
2ab30 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2ab40 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2ab50 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
2ab60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ab70 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2ab80 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2ab90 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
2aba0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2abb0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2abc0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2abd0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
2abe0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2abf0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2ac00 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
2ac10 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
2ac20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ac30 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2ac40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2ac50 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2ac60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2ac70 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
2ac80 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2ac90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
2aca0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2acb0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2acc0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73  TE_API const uns
2acd0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
2ace0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2acf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ad00 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2ad10 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2ad20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ad30 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2ad40 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2ad50 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ad60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ad70 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2ad80 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2ad90 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
2ada0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
2adb0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
2adc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2add0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
2ade0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
2adf0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2ae00 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2ae10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
2ae20 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
2ae30 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2ae40 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
2ae50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2ae60 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2ae70 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2ae80 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
2ae90 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
2aea0 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
2aeb0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2aec0 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
2aed0 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
2aee0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2aef0 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
2af00 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
2af10 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
2af20 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
2af30 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
2af40 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
2af50 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
2af60 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
2af70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
2af80 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
2af90 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2afa0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
2afb0 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
2afc0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
2afd0 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
2afe0 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
2aff0 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
2b000 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
2b010 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
2b020 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
2b030 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
2b040 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
2b050 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2b060 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
2b070 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
2b080 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2b090 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
2b0a0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2b0b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2b0c0 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
2b0d0 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
2b0e0 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
2b0f0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
2b100 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2b110 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
2b120 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
2b130 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
2b140 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
2b150 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b160 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
2b170 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
2b180 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
2b190 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
2b1a0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2b1b0 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
2b1c0 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
2b1d0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
2b1e0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
2b1f0 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
2b200 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
2b210 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
2b220 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
2b230 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
2b240 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
2b250 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
2b260 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
2b270 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
2b280 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
2b290 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
2b2a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e   int sqlite3_fin
2b2b0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
2b2c0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2b2d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2b2e0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
2b2f0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
2b300 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2b310 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
2b320 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
2b330 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
2b340 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
2b350 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
2b360 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
2b370 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
2b380 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
2b390 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
2b3a0 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
2b3b0 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
2b3c0 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
2b3d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2b3e0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
2b3f0 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
2b400 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
2b410 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
2b420 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
2b430 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
2b440 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
2b450 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
2b460 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2b470 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
2b480 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b490 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
2b4a0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
2b4b0 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
2b4c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
2b4d0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2b4e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2b4f0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2b500 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b510 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
2b520 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
2b530 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
2b540 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
2b550 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
2b560 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
2b570 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
2b580 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
2b590 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
2b5a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
2b5b0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2b5c0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2b5d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2b5e0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2b5f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b600 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
2b610 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
2b620 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2b630 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
2b640 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2b650 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2b660 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2b670 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
2b680 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
2b690 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
2b6a0 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
2b6b0 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
2b6c0 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
2b6d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
2b6e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2b6f0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
2b700 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2b710 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2b720 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
2b730 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
2b740 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
2b750 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
2b760 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2b770 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2b780 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2b790 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2b7a0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2b7b0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2b7c0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2b7d0 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  s}.**.** ^These 
2b7e0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
2b7f0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
2b800 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
2b810 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
2b820 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
2b830 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2b840 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
2b850 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
2b860 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
2b870 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
2b880 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2b890 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
2b8a0 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
2b8b0 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
2b8c0 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
2b8d0 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
2b8e0 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
2b8f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2b900 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
2b910 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
2b920 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
2b930 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
2b940 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
2b950 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
2b960 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
2b970 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2b980 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
2b990 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2b9a0 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
2b9b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
2b9c0 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
2b9d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
2b9e0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
2b9f0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2ba00 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
2ba10 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
2ba20 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
2ba30 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ba40 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2ba50 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
2ba60 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
2ba70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
2ba80 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
2ba90 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
2baa0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
2bab0 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
2bac0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
2bad0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
2bae0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
2baf0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
2bb00 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
2bb10 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
2bb20 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
2bb30 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
2bb40 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
2bb50 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
2bb60 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
2bb70 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
2bb80 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
2bb90 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
2bba0 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
2bbb0 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
2bbc0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
2bbd0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
2bbe0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
2bbf0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
2bc00 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
2bc10 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2bc20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
2bc30 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
2bc40 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
2bc50 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
2bc60 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2bc70 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2bc80 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
2bc90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
2bca0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
2bcb0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2bcc0 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
2bcd0 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
2bce0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
2bcf0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
2bd00 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
2bd10 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
2bd20 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2bd30 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
2bd40 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
2bd50 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
2bd60 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
2bd70 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
2bd80 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
2bd90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2bda0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
2bdb0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
2bdc0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
2bdd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
2bde0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
2bdf0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
2be00 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
2be10 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
2be20 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75  s.  Every SQL fu
2be30 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2be40 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62  ation must be ab
2be50 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  le to work.** wi
2be60 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
2be70 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
2be80 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
2be90 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
2bea0 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
2beb0 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
2bec0 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
2bed0 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61  er.  ^An applica
2bee0 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f  tion may.** invo
2bef0 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
2bf00 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20  e_function() or 
2bf10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2bf20 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74  unction16() mult
2bf30 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
2bf40 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
2bf50 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69  tion but with di
2bf60 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f  fferent values o
2bf70 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e  f eTextRep..** ^
2bf80 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
2bf90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2bfa0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2bfb0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
2bfc0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
2bfd0 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
2bfe0 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
2bff0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
2c000 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
2c010 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
2c020 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
2c030 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
2c040 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
2c050 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
2c060 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
2c070 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2c080 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
2c090 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
2c0a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
2c0b0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2c0c0 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
2c0d0 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
2c0e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2c0f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
2c100 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
2c110 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
2c120 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
2c130 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
2c140 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
2c150 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
2c160 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
2c170 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
2c180 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
2c190 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
2c1a0 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
2c1b0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2c1c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2c1d0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
2c1e0 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
2c1f0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2c200 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2c210 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
2c220 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
2c230 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
2c240 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
2c250 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
2c260 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
2c270 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
2c280 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
2c290 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
2c2a0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
2c2b0 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
2c2c0 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
2c2d0 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
2c2e0 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
2c2f0 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
2c300 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
2c310 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
2c320 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   pass NULL point
2c330 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
2c340 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
2c350 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
2c360 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61  (If the ninth pa
2c370 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2c380 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c390 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
2c3a0 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
2c3b0 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
2c3c0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
2c3d0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
2c3e0 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
2c3f0 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
2c400 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
2c410 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
2c420 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
2c430 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
2c440 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2c450 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
2c460 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
2c470 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
2c480 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
2c490 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
2c4a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c4b0 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
2c4c0 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
2c4d0 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
2c4e0 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
2c4f0 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
2c500 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
2c510 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
2c520 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
2c530 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
2c540 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
2c550 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
2c560 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
2c570 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2c580 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2c590 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
2c5a0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
2c5b0 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
2c5c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2c5d0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
2c5e0 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
2c5f0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
2c600 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
2c610 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
2c620 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
2c630 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
2c640 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2c650 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
2c660 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
2c670 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
2c680 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
2c690 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
2c6a0 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
2c6b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2c6c0 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
2c6d0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2c6e0 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
2c6f0 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
2c700 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
2c710 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
2c720 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
2c730 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
2c740 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
2c750 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
2c760 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
2c770 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2c780 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
2c790 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
2c7a0 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
2c7b0 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
2c7c0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2c7d0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
2c7e0 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
2c7f0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2c800 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
2c810 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
2c820 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
2c830 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
2c840 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
2c850 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
2c860 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
2c870 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
2c880 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
2c890 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
2c8a0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
2c8b0 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
2c8c0 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
2c8d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2c8e0 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
2c8f0 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
2c900 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2c910 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
2c920 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
2c930 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
2c940 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
2c950 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
2c960 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
2c970 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c980 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
2c990 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
2c9a0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
2c9b0 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
2c9c0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2c9d0 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
2c9e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
2c9f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
2ca00 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2ca10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
2ca20 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2ca30 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2ca40 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2ca50 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2ca60 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2ca70 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2ca80 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2ca90 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2caa0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2cab0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2cac0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2cad0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2cae0 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
2caf0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2cb00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2cb10 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2cb20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2cb30 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2cb40 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2cb50 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2cb60 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2cb70 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2cb80 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2cb90 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2cba0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2cbb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2cbc0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2cbd0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2cbe0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2cbf0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49  ontext*).);.SQLI
2cc00 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2cc10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2cc20 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
2cc30 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2cc40 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2cc50 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2cc60 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2cc70 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2cc80 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2cc90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2cca0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2ccb0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2ccc0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2ccd0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2cce0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2ccf0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2cd00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
2cd10 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
2cd20 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
2cd30 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
2cd40 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
2cd50 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
2cd60 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
2cd70 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
2cd80 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
2cd90 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
2cda0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
2cdb0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
2cdc0 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
2cdd0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
2cde0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
2cdf0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
2ce00 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
2ce10 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
2ce20 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
2ce30 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
2ce40 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
2ce50 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
2ce60 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
2ce70 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
2ce80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ce90 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
2cea0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2ceb0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
2cec0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2ced0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
2cee0 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
2cef0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
2cf00 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
2cf10 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
2cf20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2cf30 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
2cf40 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
2cf50 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
2cf60 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
2cf70 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
2cf80 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
2cf90 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
2cfa0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2cfb0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
2cfc0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
2cfd0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
2cfe0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
2cff0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
2d000 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
2d010 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
2d020 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
2d030 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
2d040 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
2d050 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
2d060 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
2d070 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
2d080 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  ED.SQLITE_API SQ
2d090 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2d0a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
2d0b0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
2d0c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
2d0d0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
2d0e0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2d0f0 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
2d100 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2d110 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
2d120 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2d130 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
2d140 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2d150 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
2d160 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
2d170 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
2d180 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2d190 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
2d1a0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
2d1b0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
2d1c0 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
2d1d0 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
2d1e0 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
2d1f0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
2d200 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2d210 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
2d220 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2d230 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
2d240 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2d250 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
2d260 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2d270 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
2d280 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
2d290 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alues.**.** The 
2d2a0 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
2d2b0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
2d2c0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2d2d0 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
2d2e0 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
2d2f0 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
2d300 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
2d310 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
2d320 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
2d330 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
2d340 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
2d350 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
2d360 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
2d370 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
2d380 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
2d390 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2d3a0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
2d3b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2d3c0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2d3d0 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
2d3e0 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
2d3f0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2d400 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2d410 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
2d420 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2d430 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
2d440 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
2d450 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
2d460 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d470 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
2d480 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
2d490 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2d4a0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
2d4b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2d4c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
2d4d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2d4e0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
2d4f0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
2d500 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
2d510 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2d520 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2d530 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
2d540 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
2d550 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2d560 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
2d570 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
2d580 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
2d590 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2d5a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2d5b0 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
2d5c0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
2d5d0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
2d5e0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
2d5f0 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
2d600 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
2d610 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2d620 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
2d630 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75   that  these rou
2d640 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
2d650 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
2d660 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2d670 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
2d680 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
2d690 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
2d6a0 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
2d6b0 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
2d6c0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
2d6d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d6e0 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
2d6f0 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
2d700 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
2d710 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
2d720 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
2d730 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
2d740 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
2d750 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
2d760 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d770 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
2d780 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
2d790 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
2d7a0 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
2d7b0 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
2d7c0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
2d7d0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
2d7e0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2d7f0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
2d800 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
2d810 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
2d820 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
2d830 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
2d840 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
2d850 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
2d860 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
2d870 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
2d880 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
2d890 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
2d8a0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
2d8b0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
2d8c0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
2d8d0 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
2d8e0 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
2d8f0 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
2d900 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
2d910 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
2d920 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
2d930 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
2d940 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
2d950 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
2d960 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
2d970 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
2d980 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
2d990 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
2d9a0 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
2d9b0 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
2d9c0 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
2d9d0 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
2d9e0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
2d9f0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
2da00 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
2da10 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2da20 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
2da30 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2da40 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
2da50 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
2da60 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
2da70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2da80 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
2da90 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
2daa0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2dab0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2dac0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2dad0 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
2dae0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2daf0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
2db00 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
2db10 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
2db20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
2db30 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
2db40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
2db50 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53  parameters..*/.S
2db60 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2db70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2db80 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
2db90 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2dba0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2dbb0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
2dbc0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2dbd0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2dbe0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2dbf0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2dc00 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64  *);.SQLITE_API d
2dc10 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
2dc20 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
2dc30 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2dc40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2dc50 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c  e3_value_int(sql
2dc60 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2dc70 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
2dc80 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
2dc90 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
2dca0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2dcb0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73  TE_API const uns
2dcc0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
2dcd0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
2dce0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2dcf0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2dd00 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2dd10 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
2dd20 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
2dd30 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2dd40 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2dd50 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
2dd60 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2dd70 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2dd80 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2dd90 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2dda0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2ddb0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2ddc0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
2ddd0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2dde0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2ddf0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
2de00 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
2de10 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
2de20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
2de30 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
2de40 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  ion Context.**.*
2de50 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
2de60 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
2de70 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
2de80 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
2de90 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
2dea0 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
2deb0 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
2dec0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
2ded0 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
2dee0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2def0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
2df00 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
2df10 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
2df20 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
2df30 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
2df40 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
2df50 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
2df60 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
2df70 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
2df80 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
2df90 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
2dfa0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
2dfb0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2dfc0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2dfd0 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
2dfe0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
2dff0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
2e000 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
2e010 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
2e020 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
2e030 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
2e040 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
2e050 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
2e060 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
2e070 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
2e080 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
2e090 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
2e0a0 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
2e0b0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
2e0c0 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
2e0d0 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
2e0e0 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
2e0f0 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
2e100 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
2e110 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
2e120 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
2e130 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
2e140 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
2e150 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
2e160 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
2e170 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
2e180 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2e190 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
2e1a0 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
2e1b0 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
2e1c0 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
2e1d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
2e1e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2e1f0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
2e200 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
2e210 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e  ULL pointer if N
2e220 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e   is.** less than
2e230 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
2e240 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
2e250 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20   allocate error 
2e260 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  occurs..**.** ^(
2e270 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70  The amount of sp
2e280 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ace allocated by
2e290 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2e2a0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
2e2b0 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64  is.** determined
2e2c0 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65   by the N parame
2e2d0 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63  ter on first suc
2e2e0 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43  cessful call.  C
2e2f0 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76  hanging the.** v
2e300 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62  alue of N in sub
2e310 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
2e320 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2e330 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68  e_context() with
2e340 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61  in.** the same a
2e350 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2e360 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20  n instance will 
2e370 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d  not resize the m
2e380 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
2e390 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ion.)^.**.** ^SQ
2e3a0 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
2e3b0 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d  ly frees the mem
2e3c0 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
2e3d0 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67   .** sqlite3_agg
2e3e0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2e3f0 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
2e400 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  ate query conclu
2e410 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
2e420 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d  irst parameter m
2e430 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66  ust be a copy of
2e440 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2e450 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
2e460 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
2e470 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
2e480 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
2e490 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20  to the xStep or 
2e4a0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
2e4b0 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
2e4c0 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
2e4d0 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  egate.** functio
2e4e0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
2e4f0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
2e500 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2e510 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
2e520 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
2e530 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2e540 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
2e550 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
2e560 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
2e570 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
2e580 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2e590 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
2e5a0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
2e5b0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
2e5c0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
2e5d0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2e5e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2e5f0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2e600 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
2e610 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
2e620 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
2e630 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2e640 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2e650 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2e660 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2e670 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2e680 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2e690 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2e6a0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2e6b0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2e6c0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2e6d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
2e6e0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
2e6f0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2e700 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
2e710 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
2e720 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e730 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2e740 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
2e750 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
2e760 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
2e770 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
2e780 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e790 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2e7a0 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
2e7b0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2e7c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2e7d0 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
2e7e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
2e7f0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
2e800 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
2e810 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e820 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
2e830 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
2e840 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2e850 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
2e860 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2e870 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2e880 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
2e890 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
2e8a0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
2e8b0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2e8c0 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49  unction..*/.SQLI
2e8d0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a  TE_API sqlite3 *
2e8e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2e8f0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
2e900 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
2e910 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2e920 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
2e930 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Data.**.** The 
2e940 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75  following two fu
2e950 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
2e960 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51  sed by scalar SQ
2e970 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
2e980 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
2e990 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
2e9a0 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
2e9b0 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
2e9c0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
2e9d0 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
2e9e0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
2e9f0 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
2ea00 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
2ea10 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
2ea20 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
2ea30 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
2ea40 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
2ea50 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61  eserved. This ma
2ea60 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f  y.** be used, fo
2ea70 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64  r example, to ad
2ea80 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  d a regular-expr
2ea90 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20  ession matching 
2eaa0 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69  scalar.** functi
2eab0 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
2eac0 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
2ead0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
2eae0 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a  on is stored as.
2eaf0 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
2eb00 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2eb10 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64  SQL value passed
2eb20 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20   as the regular 
2eb30 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61  expression.** pa
2eb40 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70  ttern.  The comp
2eb50 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
2eb60 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
2eb70 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
2eb80 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
2eb90 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2eba0 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68  ction so that th
2ebb0 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65  e original patte
2ebc0 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65  rn string.** doe
2ebd0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2ebe0 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65   recompiled on e
2ebf0 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  ach invocation..
2ec00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ec10 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2ec20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ec30 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2ec40 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
2ec50 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
2ec60 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
2ec70 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
2ec80 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
2ec90 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
2eca0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
2ecb0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2ecc0 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61  ion. ^If no meta
2ecd0 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76  data has been ev
2ece0 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66  er.** been set f
2ecf0 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  or the Nth argum
2ed00 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ent of the funct
2ed10 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63  ion, or if the c
2ed20 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
2ed30 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
2ed40 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73  er has changed s
2ed50 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61  ince the meta-da
2ed60 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74  ta was set,.** t
2ed70 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hen sqlite3_get_
2ed80 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e  auxdata() return
2ed90 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2eda0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2edb0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2edc0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  () interface sav
2edd0 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  es the metadata.
2ede0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
2edf0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
2ee00 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61  er as the metada
2ee10 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
2ee20 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
2ee30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2ee40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2ee50 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20    Subsequent.** 
2ee60 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2ee70 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d  _get_auxdata() m
2ee80 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73  ight return this
2ee90 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73   data, if it has
2eea0 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73  .** not been des
2eeb0 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69  troyed..** ^If i
2eec0 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  t is not NULL, S
2eed0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
2eee0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
2eef0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76  .** function giv
2ef00 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61  en by the 4th pa
2ef10 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2ef20 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2ef30 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64   on.** the metad
2ef40 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72  ata when the cor
2ef50 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
2ef60 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
2ef70 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  anges.** or when
2ef80 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2ef90 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68  nt completes, wh
2efa0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
2efb0 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  rst..**.** SQLit
2efc0 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c  e is free to cal
2efd0 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  l the destructor
2efe0 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61   and drop metada
2eff0 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72  ta on any.** par
2f000 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
2f010 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
2f020 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67  me.  ^The only g
2f030 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74  uarantee is that
2f040 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74  .** the destruct
2f050 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  or will be calle
2f060 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74  d before the met
2f070 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64  adata is dropped
2f080 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61  ..**.** ^(In pra
2f090 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
2f0a0 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
2f0b0 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
2f0c0 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65  lls for.** expre
2f0d0 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ssions that are 
2f0e0 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70  constant at comp
2f0f0 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69  ile time. This i
2f100 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a  ncludes literal.
2f110 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
2f120 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a  arameters].)^.**
2f130 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2f140 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
2f150 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2f160 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2f170 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
2f180 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2f190 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
2f1a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
2f1b0 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
2f1c0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
2f1d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
2f1e0 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
2f1f0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
2f200 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
2f210 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
2f220 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
2f230 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
2f240 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
2f250 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
2f260 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
2f270 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
2f280 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
2f290 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
2f2a0 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
2f2b0 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
2f2c0 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
2f2d0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
2f2e0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
2f2f0 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
2f300 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
2f310 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
2f320 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
2f330 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
2f340 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
2f350 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
2f360 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
2f370 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2f380 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
2f390 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
2f3a0 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
2f3b0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
2f3c0 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
2f3d0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
2f3e0 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
2f3f0 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
2f400 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
2f410 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
2f420 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
2f430 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
2f440 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
2f450 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
2f460 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
2f470 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
2f480 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
2f490 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65  lers.  See ticke
2f4a0 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65  t #2191..*/.type
2f4b0 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
2f4c0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
2f4d0 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
2f4e0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
2f4f0 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
2f500 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2f510 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
2f520 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
2f530 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
2f540 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
2f550 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
2f560 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
2f570 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
2f580 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ion.**.** These 
2f590 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
2f5a0 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
2f5b0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
2f5c0 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
2f5d0 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
2f5e0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
2f5f0 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
2f600 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f610 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
2f620 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f630 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
2f640 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
2f650 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
2f660 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
2f670 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
2f680 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
2f690 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
2f6a0 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
2f6b0 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
2f6c0 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
2f6d0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
2f6e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
2f6f0 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
2f700 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
2f710 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
2f720 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
2f730 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
2f740 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2f750 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
2f760 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2f770 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
2f780 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f790 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2f7a0 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
2f7b0 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
2f7c0 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
2f7d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2f7e0 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
2f7f0 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
2f800 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
2f810 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  hird parameter..
2f820 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2f830 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
2f840 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  ob() interfaces 
2f850 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f  set the result o
2f860 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
2f870 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2f880 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c  ction to be a BL
2f890 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c  OB containing al
2f8a0 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20  l zero.** bytes 
2f8b0 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73  and N bytes in s
2f8c0 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ize, where N is 
2f8d0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2f8e0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   2nd parameter..
2f8f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2f900 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
2f910 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2f920 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
2f930 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
2f940 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f950 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
2f960 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
2f970 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
2f980 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
2f990 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
2f9a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f9b0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
2f9c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2f9d0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
2f9e0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
2f9f0 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
2fa00 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
2fa10 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51  xception..** ^SQ
2fa20 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
2fa30 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
2fa40 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
2fa50 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
2fa60 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2fa70 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
2fa80 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
2fa90 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
2faa0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
2fab0 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72  .  ^SQLite inter
2fac0 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
2fad0 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
2fae0 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
2faf0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
2fb00 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a   UTF-8. ^SQLite.
2fb10 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  ** interprets th
2fb20 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
2fb30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2fb40 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36  or16() as UTF-16
2fb50 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
2fb60 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74  te order.  ^If t
2fb70 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2fb80 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
2fb90 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
2fba0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2fbb0 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
2fbc0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
2fbd0 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
2fbe0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2fbf0 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
2fc00 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
2fc10 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
2fc20 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
2fc30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2fc40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2fc50 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
2fc60 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2fc70 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
2fc80 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
2fc90 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
2fca0 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
2fcb0 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
2fcc0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2fcd0 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
2fce0 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73  ssage..** ^The s
2fcf0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2fd00 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
2fd10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2fd20 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
2fd30 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f  ake a private co
2fd40 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
2fd50 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
2fd60 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
2fd70 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  rn.  Hence, the 
2fd80 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
2fd90 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
2fda0 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
2fdb0 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
2fdc0 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
2fdd0 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  harm..** ^The sq
2fde0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2fdf0 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
2fe00 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
2fe10 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
2fe20 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
2fe30 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
2fe40 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
2fe50 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61  ction.  ^By defa
2fe60 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
2fe70 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
2fe80 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73  _ERROR.  ^A subs
2fe90 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
2fea0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2feb0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
2fec0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2fed0 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20  16() resets the 
2fee0 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51  error code to SQ
2fef0 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a  LITE_ERROR..**.*
2ff00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2ff10 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69  esult_toobig() i
2ff20 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
2ff30 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
2ff40 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
2ff50 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
2ff60 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
2ff70 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
2ff80 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
2ff90 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2ffa0 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
2ffb0 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
2ffc0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
2ffd0 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
2ffe0 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
2fff0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
30000 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
30010 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
30020 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
30030 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
30040 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
30050 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30060 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
30070 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
30080 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
30090 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
300a0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
300b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
300c0 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
300d0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
300e0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
300f0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
30100 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
30110 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
30120 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
30130 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
30140 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
30150 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
30160 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30170 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
30180 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
30190 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
301a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
301b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
301c0 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
301d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
301e0 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
301f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30200 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
30210 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
30220 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
30230 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
30240 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
30250 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
30260 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
30270 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30280 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
30290 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
302a0 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
302b0 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
302c0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
302d0 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
302e0 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
302f0 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
30300 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
30310 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  vely..** ^SQLite
30320 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
30330 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
30340 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
30350 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
30360 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
30370 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30380 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
30390 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
303a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
303b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
303c0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
303d0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
303e0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
303f0 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
30400 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
30410 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
30420 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
30430 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
30440 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
30450 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
30460 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
30470 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
30480 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
30490 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
304a0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
304b0 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
304c0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
304d0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
304e0 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
304f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30500 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
30510 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20  result.  If the 
30520 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
30530 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
30540 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62  hen it.** must b
30550 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
30560 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e  t into the strin
30570 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  g where the NUL 
30580 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
30590 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68  .** appear if th
305a0 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e  e string where N
305b0 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  UL terminated.  
305c0 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
305d0 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69  cters occur.** i
305e0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20  n the string at 
305f0 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68  a byte offset th
30600 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  at is less than 
30610 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
30620 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65   3rd.** paramete
30630 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  r, then the resu
30640 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c  lting string wil
30650 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  l contain embedd
30660 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a  ed NULs and the.
30670 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  ** result of exp
30680 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69  ressions operati
30690 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69  ng on strings wi
306a0 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
306b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
306c0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
306d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
306e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
306f0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
30700 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
30710 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
30720 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
30730 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
30740 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
30750 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
30760 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
30770 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
30780 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
30790 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
307a0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
307b0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
307c0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
307d0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
307e0 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
307f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
30800 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
30810 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
30820 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
30830 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
30840 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
30850 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
30860 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
30870 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
30880 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
30890 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
308a0 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
308b0 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
308c0 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
308d0 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
308e0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
308f0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
30900 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
30910 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
30920 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
30930 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
30940 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
30950 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
30960 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
30970 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
30980 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
30990 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
309a0 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
309b0 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
309c0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
309d0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
309e0 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
309f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30a00 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
30a10 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
30a20 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
30a30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
30a40 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
30a50 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
30a60 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
30a70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30a80 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
30a90 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
30aa0 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
30ab0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30ac0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
30ad0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
30ae0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
30af0 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
30b00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
30b10 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
30b20 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
30b30 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
30b40 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
30b50 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
30b60 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
30b70 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
30b80 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
30b90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30ba0 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
30bb0 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
30bc0 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
30bd0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30be0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
30bf0 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
30c00 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
30c10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30c20 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
30c30 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
30c40 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
30c50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
30c60 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
30c70 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
30c80 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
30c90 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
30ca0 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
30cb0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30cc0 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
30cd0 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
30ce0 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
30cf0 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
30d00 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
30d10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
30d20 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
30d30 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
30d40 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
30d50 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
30d60 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
30d70 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
30d80 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
30d90 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
30da0 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51  xt*, double);.SQ
30db0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
30dc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30dd0 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
30de0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
30df0 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
30e00 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
30e10 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
30e20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30e30 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
30e40 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
30e50 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
30e60 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
30e70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30e80 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
30e90 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
30ea0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
30eb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
30ec0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
30ed0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30ee0 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
30ef0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
30f00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
30f10 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
30f20 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
30f30 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  ntext*, int);.SQ
30f40 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
30f50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
30f60 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
30f70 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
30f80 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
30f90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
30fa0 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
30fb0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
30fc0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
30fd0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
30fe0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30ff0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
31000 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
31010 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
31020 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31030 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
31040 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
31050 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
31060 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
31070 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
31080 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31090 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
310a0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
310b0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
310c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
310d0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
310e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
310f0 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
31100 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
31110 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
31120 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
31130 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
31140 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
31150 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
31160 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31170 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
31180 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
31190 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
311a0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
311b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
311c0 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
311d0 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
311e0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  s.**.** ^These f
311f0 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65  unctions add, re
31200 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20  move, or modify 
31210 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73  a [collation] as
31220 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
31230 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
31240 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
31250 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
31260 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
31270 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
31280 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  he collation is 
31290 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
312a0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
312b0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
312c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
312d0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
312e0 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
312f0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
31300 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
31310 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
31320 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
31330 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e  .** ^Collation n
31340 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72  ames that compar
31350 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e  e equal accordin
31360 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  g to [sqlite3_st
31370 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a  rnicmp()] are.**
31380 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
31390 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  e the same name.
313a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69  .**.** ^(The thi
313b0 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65  rd argument (eTe
313c0 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f  xtRep) must be o
313d0 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
313e0 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  nts:.** <ul>.** 
313f0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
31400 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8],.** <li> [SQL
31410 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a  ITE_UTF16LE],.**
31420 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
31430 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16BE],.** <li> 
31440 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
31450 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
31460 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
31470 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  ]..** </ul>)^.**
31480 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61   ^The eTextRep a
31490 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e  rgument determin
314a0 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  es the encoding 
314b0 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65  of strings passe
314c0 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c  d.** to the coll
314d0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
314e0 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61  allback, xCallba
314f0 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  ck..** ^The [SQL
31500 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b  ITE_UTF16] and [
31510 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
31520 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72  GNED] values for
31530 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72   eTextRep.** for
31540 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  ce strings to be
31550 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69   UTF16 with nati
31560 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
31570 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
31580 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
31590 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70  lue for eTextRep
315a0 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20   forces strings 
315b0 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61  to begin.** on a
315c0 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72  n even byte addr
315d0 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ess..**.** ^The 
315e0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
315f0 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70   pArg, is an app
31600 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
31610 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61  inter that is pa
31620 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20  ssed.** through 
31630 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
31640 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c  ument to the col
31650 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
31660 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
31670 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
31680 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20  ent, xCallback, 
31690 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
316a0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
316b0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74  nction..** ^Mult
316c0 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  iple collating f
316d0 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20  unctions can be 
316e0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
316f0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
31700 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65  ut.** with diffe
31710 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61  rent eTextRep pa
31720 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c  rameters and SQL
31730 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69  ite will use whi
31740 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69  chever.** functi
31750 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20  on requires the 
31760 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
31770 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74  data transformat
31780 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
31790 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65  xCallback argume
317a0 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  nt is NULL then 
317b0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
317c0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c  nction is.** del
317d0 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c  eted.  ^When all
317e0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
317f0 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20  ions having the 
31800 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65  same name are de
31810 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63  leted,.** that c
31820 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c  ollation is no l
31830 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a  onger usable..**
31840 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69  .** ^The collati
31850 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
31860 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
31870 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74  with a copy of t
31880 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c  he pArg .** appl
31890 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
318a0 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77  nter and with tw
318b0 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65  o strings in the
318c0 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66   encoding specif
318d0 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54  ied.** by the eT
318e0 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e  extRep argument.
318f0 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20    The collating 
31900 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65  function must re
31910 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  turn an.** integ
31920 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74  er that is negat
31930 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f  ive, zero, or po
31940 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65  sitive.** if the
31950 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
31960 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61   less than, equa
31970 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
31980 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
31990 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
319a0 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  y.  A collating 
319b0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c  function must al
319c0 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
319d0 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67  same answer.** g
319e0 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e  iven the same in
319f0 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72  puts.  If two or
31a00 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20   more collating 
31a10 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65  functions are re
31a20 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74  gistered.** to t
31a30 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f  he same collatio
31a40 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69  n name (using di
31a50 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
31a60 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c   values) then al
31a70 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61  l.** must give a
31a80 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73  n equivalent ans
31a90 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64  wer when invoked
31aa0 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74   with equivalent
31ab0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
31ac0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
31ad0 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68  ion must obey th
31ae0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70  e following prop
31af0 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a  erties for all.*
31b00 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20  * strings A, B, 
31b10 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c  and C:.**.** <ol
31b20 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  >.** <li> If A==
31b30 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20  B then B==A..** 
31b40 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64  <li> If A==B and
31b50 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e   B==C then A==C.
31b60 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
31b70 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a  ;B THEN B&gt;A..
31b80 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
31b90 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65  B and B&lt;C the
31ba0 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f  n A&lt;C..** </o
31bb0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f  l>.**.** If a co
31bc0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
31bd0 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68   fails any of th
31be0 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69  e above constrai
31bf0 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20  nts and that.** 
31c00 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
31c10 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65  on is  registere
31c20 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e  d and used, then
31c30 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
31c40 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e   SQLite.** is un
31c50 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
31c60 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
31c70 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
31c80 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
31c90 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
31ca0 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20  ation().** with 
31cb0 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61  the addition tha
31cc0 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63  t the xDestroy c
31cd0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
31ce0 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a  ed on pArg when.
31cf0 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** the collating
31d00 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
31d10 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  eted..** ^Collat
31d20 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
31d30 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  e deleted when t
31d40 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64  hey are overridd
31d50 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63  en by later.** c
31d60 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c  alls to the coll
31d70 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
31d80 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e  unctions or when
31d90 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
31da0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
31db0 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
31dc0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
31dd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73  .**.** ^The xDes
31de0 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
31df0 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c   <u>not</u> call
31e00 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71  ed if the .** sq
31e10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
31e20 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63  lation_v2() func
31e30 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70  tion fails.  App
31e40 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69  lications that i
31e50 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
31e60 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
31e70 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f  n_v2() with a no
31e80 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20  n-NULL xDestroy 
31e90 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
31ea0 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65  .** check the re
31eb0 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69  turn code and di
31ec0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70  spose of the app
31ed0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
31ee0 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c  inter.** themsel
31ef0 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20  ves rather than 
31f00 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65  expecting SQLite
31f10 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74   to deal with it
31f20 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68   for them..** Th
31f30 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20  is is different 
31f40 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72  from every other
31f50 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
31f60 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73  e.  The inconsis
31f70 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66  tency .** is unf
31f80 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e  ortunate but can
31f90 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77  not be changed w
31fa0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
31fb0 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f  backwards .** co
31fc0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
31fd0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73  ** See also:  [s
31fe0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
31ff0 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b  _needed()] and [
32000 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
32010 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a  n_needed16()]..*
32020 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
32030 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32040 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
32050 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
32060 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
32070 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
32080 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
32090 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
320a0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
320b0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
320c0 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  id*).);.SQLITE_A
320d0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
320e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
320f0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
32100 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
32110 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
32120 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
32130 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
32140 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
32150 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
32160 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20  ,const void*),. 
32170 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
32180 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54  (void*).);.SQLIT
32190 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
321a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
321b0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
321c0 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
321d0 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
321e0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
321f0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
32200 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
32210 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
32220 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
32230 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32240 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
32250 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
32260 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
32270 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
32280 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
32290 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
322a0 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
322b0 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
322c0 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
322d0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
322e0 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
322f0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
32300 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
32310 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
32320 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
32330 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
32340 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
32350 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
32360 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
32370 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
32380 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
32390 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
323a0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
323b0 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
323c0 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
323d0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
323e0 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
323f0 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
32400 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
32410 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
32420 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
32430 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
32440 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
32450 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
32460 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
32470 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
32480 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
32490 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
324a0 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
324b0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
324c0 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
324d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
324e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
324f0 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
32500 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
32510 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
32520 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
32530 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
32540 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
32550 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
32560 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
32570 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
32580 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
32590 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
325a0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
325b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
325c0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
325d0 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
325e0 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
325f0 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
32600 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
32610 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
32620 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
32630 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
32640 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
32650 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
32660 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
32670 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
32680 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
32690 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
326a0 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
326b0 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
326c0 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
326d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
326e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
326f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32700 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
32710 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
32720 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32730 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  _v2()]..*/.SQLIT
32740 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
32750 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
32760 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
32770 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
32780 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
32790 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
327a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
327b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
327c0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
327d0 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71  n_needed16(.  sq
327e0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
327f0 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ,.  void(*)(void
32800 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
32810 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f  TextRep,const vo
32820 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20  id*).);..#ifdef 
32830 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43  SQLITE_HAS_CODEC
32840 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
32850 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
32860 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
32870 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
32880 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
32890 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
328a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
328b0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
328c0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
328d0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
328e0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
328f0 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
32900 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
32910 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
32920 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
32930 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
32940 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
32950 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
32960 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
32970 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
32980 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
32990 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
329a0 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
329b0 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
329c0 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
329d0 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
329e0 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
329f0 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
32a00 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
32a10 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
32a20 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
32a30 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
32a40 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
32a50 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
32a60 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
32a70 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
32a80 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
32a90 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
32aa0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
32ab0 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28  t sqlite3_rekey(
32ac0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
32ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32ae0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
32af0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
32b00 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
32b10 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
32b20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
32b30 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  /.);../*.** Spec
32b40 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
32b50 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45  on key for a SEE
32b60 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
32b70 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
32b80 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45  , none of the SE
32b90 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  E routines will 
32ba0 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  work..*/.SQLITE_
32bb0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
32bc0 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20  _activate_see(. 
32bd0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
32be0 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
32bf0 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
32c00 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
32c10 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  f..#ifdef SQLITE
32c20 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a  _ENABLE_CEROD./*
32c30 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
32c40 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
32c50 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62  or a CEROD datab
32c60 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
32c70 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
32c80 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f   of the CEROD ro
32c90 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
32ca0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
32cb0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
32cc0 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63  ivate_cerod(.  c
32cd0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
32ce0 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
32cf0 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
32d00 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
32d10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32d20 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
32d30 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
32d40 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ime.**.** The sq
32d50 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
32d60 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
32d70 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
32d80 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
32d90 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
32da0 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
32db0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
32dc0 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
32dd0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
32de0 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
32df0 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
32e00 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
32e10 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a  requests with.**
32e20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
32e30 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
32e40 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
32e50 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
32e60 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74  o.** the nearest
32e70 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d   second. The num
32e80 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
32e90 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
32ea0 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74  ually.** request
32eb0 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
32ec0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
32ed0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
32ee0 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e  ^SQLite implemen
32ef0 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
32f00 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
32f10 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
32f20 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
32f30 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
32f40 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65   object.  If the
32f50 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
32f60 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75  .** of the defau
32f70 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d  lt VFS is not im
32f80 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63  plemented correc
32f90 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c  tly, or not impl
32fa0 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c  emented at.** al
32fb0 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  l, then the beha
32fc0 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
32fd0 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69  sleep() may devi
32fe0 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73  ate from the des
32ff0 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74  cription.** in t
33000 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
33010 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49 54  graphs..*/.SQLIT
33020 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
33030 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
33040 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
33050 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
33060 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
33070 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
33080 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
33090 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
330a0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
330b0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
330c0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
330d0 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
330e0 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
330f0 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
33100 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
33110 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
33120 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
33130 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
33140 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
33150 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
33160 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
33170 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
33180 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
33190 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
331a0 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
331b0 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
331c0 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
331d0 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
331e0 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
331f0 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
33200 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
33210 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
33220 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
33230 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
33240 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
33250 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
33260 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
33270 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
33280 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
33290 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
332a0 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
332b0 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
332c0 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
332d0 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
332e0 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
332f0 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
33300 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
33310 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
33320 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
33330 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
33340 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
33350 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
33360 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
33370 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
33380 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
33390 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
333a0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
333b0 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
333c0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
333d0 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
333e0 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
333f0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
33400 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
33410 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
33420 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
33430 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
33440 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
33450 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
33460 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
33470 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
33480 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
33490 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
334a0 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
334b0 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
334c0 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
334d0 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
334e0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
334f0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
33500 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
33510 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
33520 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
33530 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
33540 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
33550 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
33560 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
33570 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
33580 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
33590 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
335a0 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
335b0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
335c0 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
335d0 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
335e0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58  TE_API SQLITE_EX
335f0 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
33600 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
33610 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
33620 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74  EF: Test For Aut
33630 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a  o-Commit Mode.**
33640 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f   KEYWORDS: {auto
33650 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a  commit mode}.**.
33660 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33670 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29  get_autocommit()
33680 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
33690 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
336a0 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69  * zero if the gi
336b0 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ven database con
336c0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73  nection is or is
336d0 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
336e0 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70  it mode,.** resp
336f0 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f  ectively.  ^Auto
33700 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
33710 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  n by default..**
33720 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
33730 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
33740 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
33750 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ment..** ^Autoco
33760 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d  mmit mode is re-
33770 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f  enabled by a [CO
33780 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
33790 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  CK]..**.** If ce
337a0 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
337b0 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
337c0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
337d0 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
337e0 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
337f0 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75  on (errors inclu
33800 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c  ding [SQLITE_FUL
33810 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  L], [SQLITE_IOER
33820 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  R],.** [SQLITE_N
33830 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
33840 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
33850 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
33860 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
33870 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
33880 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
33890 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
338a0 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
338b0 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53  nd out whether S
338c0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
338d0 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
338e0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
338f0 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  after.** an erro
33900 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73  r is to use this
33910 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
33920 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
33930 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
33940 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
33950 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
33960 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  .** connection w
33970 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
33980 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
33990 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
339a0 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  lue.** is undefi
339b0 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ned..*/.SQLITE_A
339c0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  PI int sqlite3_g
339d0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
339e0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
339f0 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54  CAPI3REF: Find T
33a00 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
33a10 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
33a20 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
33a30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
33a40 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
33a50 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
33a60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33a70 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
33a80 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
33a90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
33aa0 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61  longs.  ^The [da
33ab0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33ac0 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  n].** returned b
33ad0 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  y sqlite3_db_han
33ae0 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  dle is the same 
33af0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33b00 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tion].** that wa
33b10 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
33b20 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
33b30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33b40 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69  v2()] call (or i
33b50 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61  ts variants) tha
33b60 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a  t was used to.**
33b70 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
33b80 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
33b90 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c  st place..*/.SQL
33ba0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20  ITE_API sqlite3 
33bb0 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
33bc0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
33bd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33be0 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
33bf0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
33c00 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ment.**.** ^This
33c10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
33c20 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
33c30 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72  the next [prepar
33c40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66  ed statement] af
33c50 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73  ter.** pStmt ass
33c60 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
33c70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33c80 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66  ction] pDb.  ^If
33c90 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
33ca0 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
33cb0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
33cc0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
33cd0 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
33ce0 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
33cf0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
33d00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33d10 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20  on pDb.  ^If no 
33d20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33d30 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20  nt.** satisfies 
33d40 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f  the conditions o
33d50 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
33d60 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e  it returns NULL.
33d70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61  .**.** The [data
33d80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33d90 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20   pointer D in a 
33da0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
33db0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
33dc0 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74  S)] must refer t
33dd0 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  o an open databa
33de0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
33df0 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c   and in particul
33e00 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61  ar must not be a
33e10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
33e20 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
33e30 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74  ite3_stmt *sqlit
33e40 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c  e3_next_stmt(sql
33e50 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74  ite3 *pDb, sqlit
33e60 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
33e70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33e80 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c  : Commit And Rol
33e90 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69  lback Notificati
33ea0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
33eb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33ec0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e  commit_hook() in
33ed0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
33ee0 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
33ef0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
33f00 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
33f10 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
33f20 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69   [COMMIT | commi
33f30 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  tted]..** ^Any c
33f40 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
33f50 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
33f60 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
33f70 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
33f80 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
33f90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
33fa0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
33fb0 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  he sqlite3_rollb
33fc0 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ack_hook() inter
33fd0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
33fe0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
33ff0 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
34000 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
34010 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52  ransaction is [R
34020 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64  OLLBACK | rolled
34030 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20   back]..** ^Any 
34040 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
34050 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
34060 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  to sqlite3_rollb
34070 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  ack_hook().** fo
34080 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
34090 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
340a0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
340b0 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d   ^The pArg argum
340c0 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68  ent is passed th
340d0 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c  rough to the cal
340e0 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68  lback..** ^If th
340f0 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
34100 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
34110 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e  tion returns non
34120 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74  -zero,.** then t
34130 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
34140 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
34150 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
34160 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
34170 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e  t_hook(D,C,P) an
34180 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  d sqlite3_rollba
34190 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66  ck_hook(D,C,P) f
341a0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75  unctions.** retu
341b0 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e  rn the P argumen
341c0 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
341d0 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20  ous call of the 
341e0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
341f0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
34200 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34210 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f  n] D, or NULL fo
34220 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63  r.** the first c
34230 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e  all for each fun
34240 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a  ction on D..**.*
34250 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  * The callback i
34260 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
34270 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
34280 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
34290 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
342a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
342b0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
342c0 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61  callback.  Any a
342d0 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
342e0 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
342f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
34300 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
34310 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
34320 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
34330 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
34340 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
34350 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69  ggered the commi
34360 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  t.** or rollback
34370 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72   hook in the fir
34380 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74  st place..** Not
34390 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
343a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
343b0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
343c0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
343d0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
343e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
343f0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
34400 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
34410 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
34420 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61  * ^Registering a
34430 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64   NULL function d
34440 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c  isables the call
34450 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  back..**.** ^Whe
34460 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  n the commit hoo
34470 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  k callback routi
34480 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ne returns zero,
34490 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a   the [COMMIT].**
344a0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c   operation is al
344b0 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75  lowed to continu
344c0 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66  e normally.  ^If
344d0 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
344e0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
344f0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b  zero, then the [
34500 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65  COMMIT] is conve
34510 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c  rted into a [ROL
34520 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20  LBACK]..** ^The 
34530 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73  rollback hook is
34540 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f   invoked on a ro
34550 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75  llback that resu
34560 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69  lts from a commi
34570 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e  t.** hook return
34580 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75  ing non-zero, ju
34590 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62  st as it would b
345a0 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72  e with any other
345b0 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
345c0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
345d0 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
345e0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
345f0 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
34600 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  en.** rolled bac
34610 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74  k if an explicit
34620 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74   "ROLLBACK" stat
34630 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
34640 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  d, or.** an erro
34650 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20  r or constraint 
34660 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63  causes an implic
34670 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f  it rollback to o
34680 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ccur..** ^The ro
34690 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
346a0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
346b0 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
346c0 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
346d0 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
346e0 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
346f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34700 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
34710 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
34720 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
34730 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ok()] interface.
34740 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
34750 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
34760 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
34770 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
34780 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
34790 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
347a0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
347b0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
347c0 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64  *)(void *), void
347d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
347e0 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65  REF: Data Change
347f0 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
34800 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
34810 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  he sqlite3_updat
34820 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  e_hook() interfa
34830 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
34840 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
34850 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
34860 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34870 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  n] identified by
34880 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
34890 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ent.** to be inv
348a0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
348b0 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
348c0 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
348d0 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ted..** ^Any cal
348e0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
348f0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
34900 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
34910 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
34920 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34930 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
34940 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
34950 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  nd argument is a
34960 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
34970 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f  function to invo
34980 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77  ke when a.** row
34990 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
349a0 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
349b0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
349c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
349d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
349e0 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20  py of the third 
349f0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
34a00 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
34a10 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65  ok()..** ^The se
34a20 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72  cond callback ar
34a30 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
34a40 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d   [SQLITE_INSERT]
34a50 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  , [SQLITE_DELETE
34a60 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
34a70 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64  _UPDATE], depend
34a80 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61  ing on the opera
34a90 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64  tion that caused
34aa0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
34ab0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a   to be invoked..
34ac0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e  ** ^The third an
34ad0 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  d fourth argumen
34ae0 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ts to the callba
34af0 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74  ck contain point
34b00 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ers to the.** da
34b10 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65  tabase and table
34b20 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67   name containing
34b30 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f   the affected ro
34b40 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c  w..** ^The final
34b50 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65   callback parame
34b60 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69  ter is the [rowi
34b70 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a  d] of the row..*
34b80 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f  * ^In the case o
34b90 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69  f an update, thi
34ba0 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  s is the [rowid]
34bb0 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74   after the updat
34bc0 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a  e takes place..*
34bd0 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74  *.** ^(The updat
34be0 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e  e hook is not in
34bf0 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72  voked when inter
34c00 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65  nal system table
34c10 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65  s are.** modifie
34c20 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d  d (i.e. sqlite_m
34c30 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65  aster and sqlite
34c40 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a  _sequence).)^.**
34c50 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72  .** ^In the curr
34c60 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
34c70 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68  on, the update h
34c80 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e  ook.** is not in
34c90 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69  voked when dupli
34ca0 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20  cation rows are 
34cb0 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20  deleted because 
34cc0 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e  of an.** [ON CON
34cd0 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c  FLICT | ON CONFL
34ce0 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61  ICT REPLACE] cla
34cf0 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68  use.  ^Nor is th
34d00 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
34d10 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f   invoked when ro
34d20 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75  ws are deleted u
34d30 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61  sing the [trunca
34d40 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
34d50 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69  ..** The excepti
34d60 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74  ons defined in t
34d70 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69  his paragraph mi
34d80 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20  ght change in a 
34d90 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73  future.** releas
34da0 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
34db0 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f  ** The update ho
34dc0 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ok implementatio
34dd0 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
34de0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
34df0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
34e00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34e10 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
34e20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e  the update hook.
34e30 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a    Any actions.**
34e40 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64   to modify the d
34e50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34e60 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72  on must be defer
34e70 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20  red until after 
34e80 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f  the.** completio
34e90 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
34ea0 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74  3_step()] call t
34eb0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
34ec0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a  e update hook..*
34ed0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
34ee0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34ef0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34f00 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
34f10 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
34f20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34f30 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
34f40 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
34f50 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
34f60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34f70 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
34f80 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a  D,C,P) function.
34f90 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50  ** returns the P
34fa0 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
34fb0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
34fc0 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
34fd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34fe0 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c  tion] D, or NULL
34ff0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73   for.** the firs
35000 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a  t call on D..**.
35010 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
35020 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
35030 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c  hook()] and [sql
35040 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
35050 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ok()].** interfa
35060 63 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ces..*/.SQLITE_A
35070 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
35080 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
35090 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
350a0 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
350b0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
350c0 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
350d0 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
350e0 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
350f0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
35100 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
35110 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b  Pager Cache.** K
35120 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64  EYWORDS: {shared
35130 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28   cache}.**.** ^(
35140 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61  This routine ena
35150 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
35160 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20   the sharing of 
35170 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63  the database cac
35180 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61  he.** and schema
35190 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
351a0 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61   between [databa
351b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20  se connection | 
351c0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20  connections].** 
351d0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
351e0 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73  base. Sharing is
351f0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
35200 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65  argument is true
35210 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64  .** and disabled
35220 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
35230 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a   is false.)^.**.
35240 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e  ** ^Cache sharin
35250 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
35260 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e   disabled for an
35270 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
35280 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68  .** This is a ch
35290 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74  ange as of SQLit
352a0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e  e version 3.5.0.
352b0 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f   In prior versio
352c0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a  ns of SQLite,.**
352d0 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61   sharing was ena
352e0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
352f0 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64   for each thread
35300 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
35310 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73  ** ^(The cache s
35320 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
35330 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
35340 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
35350 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
35360 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
35370 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
35380 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
35390 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
353a0 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  )]..** Existing 
353b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
353c0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
353d0 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
353e0 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69  de.** that was i
353f0 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
35400 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f  time they were o
35410 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  pened.)^.**.** ^
35420 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  (This routine re
35430 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
35440 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
35450 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  e was enabled or
35460 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63   disabled.** suc
35470 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b  cessfully.  An [
35480 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
35490 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73  eturned otherwis
354a0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72  e.)^.**.** ^Shar
354b0 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
354c0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
354d0 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20   But this might 
354e0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74  change in.** fut
354f0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
35500 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61  SQLite.  Applica
35510 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20  tions that care 
35520 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20  about shared.** 
35530 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68  cache setting sh
35540 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c  ould set it expl
35550 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  icitly..**.** Se
35560 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65  e Also:  [SQLite
35570 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f   Shared-Cache Mo
35580 64 65 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  de].*/.SQLITE_AP
35590 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  I int sqlite3_en
355a0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
355b0 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e(int);../*.** C
355c0 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74  API3REF: Attempt
355d0 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
355e0 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  mory.**.** ^The 
355f0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
35600 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61  memory() interfa
35610 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66  ce attempts to f
35620 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f  ree N bytes.** o
35630 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
35640 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
35650 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
35660 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a  ry allocations.*
35670 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61  * held by the da
35680 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20  tabase library. 
35690 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f    Memory used to
356a0 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a   cache database.
356b0 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72  ** pages to impr
356c0 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
356d0 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
356e0 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
356f0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74  emory..** ^sqlit
35700 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
35710 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  y() returns the 
35720 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
35730 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a  actually freed,.
35740 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  ** which might b
35750 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74  e more or less t
35760 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72  han the amount r
35770 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68  equested..** ^Th
35780 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
35790 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 69  e_memory() routi
357a0 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65  ne is a no-op re
357b0 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20  turning zero.** 
357c0 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74  if SQLite is not
357d0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
357e0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
357f0 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
35800 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
35810 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  int sqlite3_rele
35820 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b  ase_memory(int);
35830 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35840 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74  : Impose A Limit
35850 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a   On Heap Size.**
35860 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35870 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
35880 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
35890 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65 72 69  ets and/or queri
358a0 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c  es the.** soft l
358b0 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75  imit on the amou
358c0 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
358d0 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
358e0 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
358f0 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74  e..** ^SQLite st
35900 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20 68 65  rives to keep he
35910 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a  ap memory utiliz
35920 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20  ation below the 
35930 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d  soft heap.** lim
35940 69 74 20 62 79 20 72 65 64 75 63 69 6e 67 20 74  it by reducing t
35950 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
35960 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70  es held in the p
35970 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 73 20  age cache.** as 
35980 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 61 67  heap memory usag
35990 65 73 20 61 70 70 72 6f 61 63 68 65 73 20 74 68  es approaches th
359a0 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65  e limit..** ^The
359b0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
359c0 20 69 73 20 22 73 6f 66 74 22 20 62 65 63 61 75   is "soft" becau
359d0 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68 20 53  se even though S
359e0 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f  QLite strives to
359f0 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74   stay.** below t
35a00 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c  he limit, it wil
35a10 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c 69 6d  l exceed the lim
35a20 69 74 20 72 61 74 68 65 72 20 74 68 61 6e 20 67  it rather than g
35a30 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53  enerate.** an [S
35a40 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72  QLITE_NOMEM] err
35a50 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  or.  In other wo
35a60 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20 68 65  rds, the soft he
35a70 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20  ap limit .** is 
35a80 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a  advisory only..*
35a90 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
35aa0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
35ab0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
35ac0 6d 69 74 36 34 28 29 20 69 73 20 74 68 65 20 73  mit64() is the s
35ad0 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f  ize of.** the so
35ae0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 70 72  ft heap limit pr
35af0 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e  ior to the call.
35b00 20 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65    ^If the argume
35b10 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  nt N is negative
35b20 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e  .** then no chan
35b30 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20 74 68  ge is made to th
35b40 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
35b50 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  t.  Hence, the c
35b60 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f  urrent.** size o
35b70 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  f the soft heap 
35b80 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64 65 74  limit can be det
35b90 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b  ermined by invok
35ba0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
35bb0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
35bc0 28 29 20 77 69 74 68 20 61 20 6e 65 67 61 74 69  () with a negati
35bd0 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  ve argument..**.
35be0 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d  ** ^If the argum
35bf0 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20 74 68  ent N is zero th
35c00 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  en the soft heap
35c10 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61 62 6c   limit is disabl
35c20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ed..**.** ^(The 
35c30 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
35c40 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20  is not enforced 
35c50 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  in the current i
35c60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
35c70 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   if one or more 
35c80 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  of following con
35c90 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72 75 65  ditions are true
35ca0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
35cb0 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20 68 65  <li> The soft he
35cc0 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20  ap limit is set 
35cd0 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e  to zero..** <li>
35ce0 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69   Memory accounti
35cf0 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 20 75  ng is disabled u
35d00 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74 69  sing a combinati
35d10 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  on of the.**    
35d20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69    [sqlite3_confi
35d30 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
35d40 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e  G_MEMSTATUS],...
35d50 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f 70 74  ) start-time opt
35d60 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ion and.**      
35d70 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  the [SQLITE_DEFA
35d80 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  ULT_MEMSTATUS] c
35d90 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
35da0 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61  on..** <li> An a
35db0 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 65 20  lternative page 
35dc0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
35dd0 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66 69 65  tion is specifie
35de0 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
35df0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
35e00 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
35e10 50 43 41 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a  PCACHE],...)..**
35e20 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65 20 63   <li> The page c
35e30 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73 20 66  ache allocates f
35e40 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f  rom its own memo
35e50 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64  ry pool supplied
35e60 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73 71 6c  .**      by [sql
35e70 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
35e80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
35e90 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68  CACHE],...) rath
35ea0 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
35eb0 66 72 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a  from the heap..*
35ec0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
35ed0 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53  Beginning with S
35ee0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
35ef0 37 2e 33 2c 20 74 68 65 20 73 6f 66 74 20 68 65  7.3, the soft he
35f00 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f  ap limit is enfo
35f10 72 63 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65  rced.** regardle
35f20 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
35f30 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
35f40 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d  _ENABLE_MEMORY_M
35f50 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f  ANAGEMENT].** co
35f60 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
35f70 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57  n is invoked.  W
35f80 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  ith [SQLITE_ENAB
35f90 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
35fa0 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f  MENT],.** the so
35fb0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
35fc0 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76 65   enforced on eve
35fd0 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
35fe0 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a  tion.  Without.*
35ff0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
36000 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
36010 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74 20 68 65  NT], the soft he
36020 61 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79  ap limit is only
36030 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65   enforced.** whe
36040 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f  n memory is allo
36050 63 61 74 65 64 20 62 79 20 74 68 65 20 70 61 67  cated by the pag
36060 65 20 63 61 63 68 65 2e 20 20 54 65 73 74 69 6e  e cache.  Testin
36070 67 20 73 75 67 67 65 73 74 73 20 74 68 61 74 20  g suggests that 
36080 62 65 63 61 75 73 65 0a 2a 2a 20 74 68 65 20 70  because.** the p
36090 61 67 65 20 63 61 63 68 65 20 69 73 20 74 68 65  age cache is the
360a0 20 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d   predominate mem
360b0 6f 72 79 20 75 73 65 72 20 69 6e 20 53 51 4c 69  ory user in SQLi
360c0 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  te, most.** appl
360d0 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63  ications will ac
360e0 68 69 65 76 65 20 61 64 65 71 75 61 74 65 20 73  hieve adequate s
360f0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 65  oft heap limit e
36100 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69 74 68 6f  nforcement witho
36110 75 74 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  ut.** the use of
36120 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
36130 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
36140 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69  T]..**.** The ci
36150 72 63 75 6d 73 74 61 6e 63 65 73 20 75 6e 64 65  rcumstances unde
36160 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 20 77  r which SQLite w
36170 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68 65 20  ill enforce the 
36180 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
36190 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69  may.** changes i
361a0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
361b0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
361c0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
361d0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
361e0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
361f0 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64(sqlite3_int64
36200 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
36210 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
36220 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d 69 74   Soft Heap Limit
36230 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44 45   Interface.** DE
36240 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
36250 68 69 73 20 69 73 20 61 20 64 65 70 72 65 63 61  his is a depreca
36260 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  ted version of t
36270 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  he [sqlite3_soft
36280 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
36290 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20  .** interface.  
362a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
362b0 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68 69 73  provided for his
362c0 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
362d0 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20  ility.** only.  
362e0 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  All new applicat
362f0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 65 20  ions should use 
36300 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
36310 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
36320 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  4()] interface r
36330 61 74 68 65 72 20 74 68 61 6e 20 74 68 69 73 20  ather than this 
36340 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  one..*/.SQLITE_A
36350 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
36360 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65  ATED void sqlite
36370 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
36380 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a  t(int N);.../*.*
36390 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 72  * CAPI3REF: Extr
363a0 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f  act Metadata Abo
363b0 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41  ut A Column Of A
363c0 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68   Table.**.** ^Th
363d0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
363e0 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75  ns metadata abou
363f0 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c  t a specific col
36400 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69  umn of a specifi
36410 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61  c.** database ta
36420 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75  ble accessible u
36430 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61  sing the [databa
36440 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
36450 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20  andle.** passed 
36460 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e  as the first fun
36470 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
36480 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d  **.** ^The colum
36490 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20  n is identified 
364a0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74  by the second, t
364b0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
364c0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a  parameters to.**
364d0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
364e0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
364f0 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20  meter is either 
36500 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
36510 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65  database.** (i.e
36520 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22  . "main", "temp"
36530 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64  , or an attached
36540 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61   database) conta
36550 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66  ining the specif
36560 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20  ied.** table or 
36570 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73 20  NULL. ^If it is 
36580 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61  NULL, then all a
36590 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
365a0 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a  s are searched.*
365b0 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20  * for the table 
365c0 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
365d0 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79  lgorithm used by
365e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
365f0 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c  gine to.** resol
36600 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74  ve unqualified t
36610 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e  able references.
36620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
36630 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
36640 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
36650 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65  function are the
36660 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
36670 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65  n.** name of the
36680 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c   desired column,
36690 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e   respectively. N
366a0 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
366b0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61  parameters.** ma
366c0 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  y be NULL..**.**
366d0 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20 72 65   ^Metadata is re
366e0 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e  turned by writin
366f0 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20  g to the memory 
36700 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64  locations passed
36710 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61   as the 5th.** a
36720 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61  nd subsequent pa
36730 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
36740 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20   function. ^Any 
36750 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e  of these argumen
36760 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c  ts may be.** NUL
36770 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  L, in which case
36780 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
36790 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65  ng element of me
367a0 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65  tadata is omitte
367b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63  d..**.** ^(<bloc
367c0 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
367d0 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
367e0 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65   <tr><th> Parame
367f0 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c  ter <th> Output<
36800 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65  br>Type <th>  De
36810 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  scription.**.** 
36820 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64  <tr><td> 5th <td
36830 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74  > const char* <t
36840 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20  d> Data type.** 
36850 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64  <tr><td> 6th <td
36860 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74  > const char* <t
36870 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75  d> Name of defau
36880 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  lt collation seq
36890 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  uence.** <tr><td
368a0 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20  > 7th <td> int  
368b0 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65         <td> True
368c0 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61   if column has a
368d0 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
368e0 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  aint.** <tr><td>
368f0 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   8th <td> int   
36900 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
36910 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72  if column is par
36920 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59  t of the PRIMARY
36930 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   KEY.** <tr><td>
36940 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   9th <td> int   
36950 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
36960 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55  if column is [AU
36970 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20  TOINCREMENT].** 
36980 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
36990 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
369a0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f  * ^The memory po
369b0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
369c0 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65  character pointe
369d0 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20  rs returned for 
369e0 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69  the.** declarati
369f0 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c  on type and coll
36a00 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
36a10 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74  s valid only unt
36a20 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63  il the next.** c
36a30 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74  all to any SQLit
36a40 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a  e API function..
36a50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  **.** ^If the sp
36a60 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73  ecified table is
36a70 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77   actually a view
36a80 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  , an [error code
36a90 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
36aa0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  *.** ^If the spe
36ab0 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73  cified column is
36ac0 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20   "rowid", "oid" 
36ad0 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64  or "_rowid_" and
36ae0 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20   an.** [INTEGER 
36af0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c  PRIMARY KEY] col
36b00 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70  umn has been exp
36b10 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
36b20 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
36b30 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  t.** parameters 
36b40 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20  are set for the 
36b50 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
36b60 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66  red column. ^(If
36b70 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20   there is no.** 
36b80 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
36b90 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49  red [INTEGER PRI
36ba0 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e  MARY KEY] column
36bb0 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
36bc0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  t.** parameters 
36bd0 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f  are set as follo
36be0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  ws:.**.** <pre>.
36bf0 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65  **     data type
36c00 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20  : "INTEGER".**  
36c10 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71     collation seq
36c20 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a  uence: "BINARY".
36c30 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a  **     not null:
36c40 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72   0.**     primar
36c50 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20  y key: 1.**     
36c60 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20  auto increment: 
36c70 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a  0.** </pre>)^.**
36c80 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74  .** ^(This funct
36c90 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65  ion may load one
36ca0 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73   or more schemas
36cb0 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66   from database f
36cc0 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65  iles. If an.** e
36cd0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
36ce0 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c  ng this process,
36cf0 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65   or if the reque
36d00 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f  sted table or co
36d10 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62  lumn.** cannot b
36d20 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72  e found, an [err
36d30 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
36d40 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f  rned and an erro
36d50 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a  r message left.*
36d60 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * in the [databa
36d70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
36d80 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20  to be retrieved 
36d90 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72  using sqlite3_er
36da0 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a  rmsg()).)^.**.**
36db0 20 5e 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e   ^This API is on
36dc0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
36dd0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
36de0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
36df0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
36e00 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
36e10 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
36e20 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
36e30 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
36e40 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61  I int sqlite3_ta
36e50 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64  ble_column_metad
36e60 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ata(.  sqlite3 *
36e70 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
36e80 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e     /* Connection
36e90 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
36ea0 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
36eb0 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61  ,        /* Data
36ec0 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c  base name or NUL
36ed0 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  L */.  const cha
36ee0 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20  r *zTableName,  
36ef0 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65     /* Table name
36f00 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
36f10 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20   *zColumnName,  
36f20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65    /* Column name
36f30 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
36f40 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20   **pzDataType,  
36f50 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63    /* OUTPUT: Dec
36f60 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20  lared data type 
36f70 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
36f80 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20  **pzCollSeq,    
36f90 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c   /* OUTPUT: Coll
36fa0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e  ation sequence n
36fb0 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e  ame */.  int *pN
36fc0 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20  otNull,         
36fd0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
36fe0 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c  True if NOT NULL
36ff0 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73   constraint exis
37000 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72  ts */.  int *pPr
37010 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20  imaryKey,       
37020 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
37030 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61  rue if column pa
37040 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e  rt of PK */.  in
37050 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20  t *pAutoinc     
37060 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
37070 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
37080 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72  umn is auto-incr
37090 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  ement */.);../*.
370a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61  ** CAPI3REF: Loa
370b0 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a  d An Extension.*
370c0 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
370d0 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51  face loads an SQ
370e0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
370f0 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20  ibrary from the 
37100 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  named file..**.*
37110 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
37120 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
37130 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
37140 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a  ts to load an.**
37150 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
37160 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  n library contai
37170 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20  ned in the file 
37180 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  zFile..**.** ^Th
37190 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73  e entry point is
371a0 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f   zProc..** ^zPro
371b0 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77  c may be 0, in w
371c0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61  hich case the na
371d0 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20  me of the entry 
371e0 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74  point.** default
371f0 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78  s to "sqlite3_ex
37200 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a  tension_init"..*
37210 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
37220 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
37230 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
37240 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  s.** [SQLITE_OK]
37250 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
37260 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
37270 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73  f something goes
37280 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61   wrong..** ^If a
37290 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61  n error occurs a
372a0 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e  nd pzErrMsg is n
372b0 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a  ot 0, then the.*
372c0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  * [sqlite3_load_
372d0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
372e0 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74  erface shall att
372f0 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20  empt to.** fill 
37300 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65  *pzErrMsg with e
37310 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
37320 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f  t stored in memo
37330 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  ry.** obtained f
37340 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
37350 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c  loc()]. The call
37360 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ing function.** 
37370 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73  should free this
37380 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69   memory by calli
37390 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
373a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65  ()]..**.** ^Exte
373b0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75  nsion loading mu
373c0 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73  st be enabled us
373d0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
373e0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
373f0 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74  nsion()] prior t
37400 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41  o calling this A
37410 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  PI,.** otherwise
37420 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62   an error will b
37430 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  e returned..**.*
37440 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
37450 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
37460 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
37470 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
37480 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  t sqlite3_load_e
37490 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69  xtension(.  sqli
374a0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
374b0 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78    /* Load the ex
374c0 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69  tension into thi
374d0 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  s database conne
374e0 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  ction */.  const
374f0 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20   char *zFile,   
37500 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
37510 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63  shared library c
37520 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73  ontaining extens
37530 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
37540 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f  har *zProc,    /
37550 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20  * Entry point.  
37560 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69  Derived from zFi
37570 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61  le if 0 */.  cha
37580 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20  r **pzErrMsg    
37590 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20     /* Put error 
375a0 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20  message here if 
375b0 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  not 0 */.);../*.
375c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
375d0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
375e0 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
375f0 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f  .**.** ^So as no
37600 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69  t to open securi
37610 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65  ty holes in olde
37620 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  r applications t
37630 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65  hat are.** unpre
37640 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69  pared to deal wi
37650 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  th extension loa
37660 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d  ding, and as a m
37670 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e  eans of disablin
37680 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c  g.** extension l
37690 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61  oading while eva
376a0 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74  luating user-ent
376b0 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f  ered SQL, the fo
376c0 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69  llowing API.** i
376d0 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75  s provided to tu
376e0 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  rn the [sqlite3_
376f0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
37700 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61  ] mechanism on a
37710 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45  nd off..**.** ^E
37720 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
37730 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75   is off by defau
37740 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23  lt. See ticket #
37750 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74  1863..** ^Call t
37760 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  he sqlite3_enabl
37770 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
37780 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  () routine with 
37790 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74  onoff==1.** to t
377a0 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  urn extension lo
377b0 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c  ading on and cal
377c0 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d  l it with onoff=
377d0 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74  =0 to turn.** it
377e0 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e   back off again.
377f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
37800 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
37810 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
37820 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e  (sqlite3 *db, in
37830 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
37840 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d   CAPI3REF: Autom
37850 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 53 74  atically Load St
37860 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b 65 64 20  atically Linked 
37870 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Extensions.**.**
37880 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
37890 20 63 61 75 73 65 73 20 74 68 65 20 78 45 6e 74   causes the xEnt
378a0 72 79 50 6f 69 6e 74 28 29 20 66 75 6e 63 74 69  ryPoint() functi
378b0 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
378c0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 6e 65 77   for.** each new
378d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
378e0 63 74 69 6f 6e 5d 20 74 68 61 74 20 69 73 20 63  ction] that is c
378f0 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 64 65  reated.  The ide
37900 61 20 68 65 72 65 20 69 73 20 74 68 61 74 0a 2a  a here is that.*
37910 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  * xEntryPoint() 
37920 69 73 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  is the entry poi
37930 6e 74 20 66 6f 72 20 61 20 73 74 61 74 69 63 61  nt for a statica
37940 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51 4c 69 74  lly linked SQLit
37950 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a 2a 20 74  e extension.** t
37960 68 61 74 20 69 73 20 74 6f 20 62 65 20 61 75 74  hat is to be aut
37970 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f 61 64 65  omatically loade
37980 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65 77 20 64  d into all new d
37990 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
379a0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  ons..**.** ^(Eve
379b0 6e 20 74 68 6f 75 67 68 20 74 68 65 20 66 75 6e  n though the fun
379c0 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79 70 65 20  ction prototype 
379d0 73 68 6f 77 73 20 74 68 61 74 20 78 45 6e 74 72  shows that xEntr
379e0 79 50 6f 69 6e 74 28 29 20 74 61 6b 65 73 0a 2a  yPoint() takes.*
379f0 2a 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 61  * no arguments a
37a00 6e 64 20 72 65 74 75 72 6e 73 20 76 6f 69 64 2c  nd returns void,
37a10 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
37a20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 69  xEntryPoint() wi
37a30 74 68 20 74 68 72 65 65 0a 2a 2a 20 61 72 67 75  th three.** argu
37a40 6d 65 6e 74 73 20 61 6e 64 20 65 78 70 65 63 74  ments and expect
37a50 73 20 61 6e 64 20 69 6e 74 65 67 65 72 20 72 65  s and integer re
37a60 73 75 6c 74 20 61 73 20 69 66 20 74 68 65 20 73  sult as if the s
37a70 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68 65 0a  ignature of the.
37a80 2a 2a 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 77  ** entry point w
37a90 68 65 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  here as follows:
37aa0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
37ab0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 26 6e 62 73  te><pre>.** &nbs
37ac0 70 3b 20 20 69 6e 74 20 78 45 6e 74 72 79 50 6f  p;  int xEntryPo
37ad0 69 6e 74 28 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  int(.** &nbsp;  
37ae0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 2a    sqlite3 *db,.*
37af0 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e 73  * &nbsp;    cons
37b00 74 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73  t char **pzErrMs
37b10 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20  g,.** &nbsp;    
37b20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
37b30 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65  ite3_api_routine
37b40 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a 20 26 6e 62  s *pThunk.** &nb
37b50 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65  sp;  );.** </pre
37b60 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
37b70 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 45  .**.** If the xE
37b80 6e 74 72 79 50 6f 69 6e 74 20 72 6f 75 74 69 6e  ntryPoint routin
37b90 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 20  e encounters an 
37ba0 65 72 72 6f 72 2c 20 69 74 20 73 68 6f 75 6c 64  error, it should
37bb0 20 6d 61 6b 65 20 2a 70 7a 45 72 72 4d 73 67 0a   make *pzErrMsg.
37bc0 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ** point to an a
37bd0 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
37be0 20 6d 65 73 73 61 67 65 20 28 6f 62 74 61 69 6e   message (obtain
37bf0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
37c00 5f 6d 70 72 69 6e 74 66 28 29 5d 29 0a 2a 2a 20  _mprintf()]).** 
37c10 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 61 70  and return an ap
37c20 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
37c30 20 63 6f 64 65 5d 2e 20 20 5e 53 51 4c 69 74 65   code].  ^SQLite
37c40 20 65 6e 73 75 72 65 73 20 74 68 61 74 20 2a 70   ensures that *p
37c50 7a 45 72 72 4d 73 67 0a 2a 2a 20 69 73 20 4e 55  zErrMsg.** is NU
37c60 4c 4c 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e  LL before callin
37c70 67 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e  g the xEntryPoin
37c80 74 28 29 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  t().  ^SQLite wi
37c90 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71  ll invoke.** [sq
37ca0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
37cb0 20 2a 70 7a 45 72 72 4d 73 67 20 61 66 74 65 72   *pzErrMsg after
37cc0 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 72   xEntryPoint() r
37cd0 65 74 75 72 6e 73 2e 20 20 5e 49 66 20 61 6e 79  eturns.  ^If any
37ce0 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  .** xEntryPoint(
37cf0 29 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  ) returns an err
37d00 6f 72 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  or, the [sqlite3
37d10 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
37d20 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
37d30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
37d40 6e 5f 76 32 28 29 5d 20 63 61 6c 6c 20 74 68 61  n_v2()] call tha
37d50 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 78  t provoked the x
37d60 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 69 6c  EntryPoint() wil
37d70 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 43  l fail..**.** ^C
37d80 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 61  alling sqlite3_a
37d90 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 58 29  uto_extension(X)
37da0 20 77 69 74 68 20 61 6e 20 65 6e 74 72 79 20 70   with an entry p
37db0 6f 69 6e 74 20 58 20 74 68 61 74 20 69 73 20 61  oint X that is a
37dc0 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e 20 74 68 65  lready.** on the
37dd0 20 6c 69 73 74 20 6f 66 20 61 75 74 6f 6d 61 74   list of automat
37de0 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 73  ic extensions is
37df0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
37e00 70 2e 20 5e 4e 6f 20 65 6e 74 72 79 20 70 6f 69  p. ^No entry poi
37e10 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 63 61  nt.** will be ca
37e20 6c 6c 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  lled more than o
37e30 6e 63 65 20 66 6f 72 20 65 61 63 68 20 64 61 74  nce for each dat
37e40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37e50 20 74 68 61 74 20 69 73 20 6f 70 65 6e 65 64 2e   that is opened.
37e60 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
37e70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f   [sqlite3_reset_
37e80 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
37e90 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
37ea0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74   int sqlite3_aut
37eb0 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64  o_extension(void
37ec0 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28   (*xEntryPoint)(
37ed0 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void));../*.** C
37ee0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
37ef0 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69  utomatic Extensi
37f00 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a  on Loading.**.**
37f10 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
37f20 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 61 75   disables all au
37f30 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
37f40 6e 73 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  ns previously.**
37f50 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
37f60 67 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  g [sqlite3_auto_
37f70 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f  extension()]..*/
37f80 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
37f90 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61   sqlite3_reset_a
37fa0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
37fb0 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  id);../*.** The 
37fc0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
37fd0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
37fe0 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72  echanism is curr
37ff0 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
38000 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
38010 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
38020 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
38030 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
38040 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
38050 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
38060 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
38070 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
38080 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
38090 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
380a0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
380b0 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69  echanism stabili
380c0 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63  zes, we will dec
380d0 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65  lare the.** inte
380e0 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70  rface fixed, sup
380f0 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69  port it indefini
38100 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65  tely, and remove
38110 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a   this comment..*
38120 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75  /../*.** Structu
38130 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20  res used by the 
38140 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e  virtual table in
38150 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64  terface.*/.typed
38160 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
38170 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76  3_vtab sqlite3_v
38180 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72  tab;.typedef str
38190 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
381a0 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69  x_info sqlite3_i
381b0 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64  ndex_info;.typed
381c0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
381d0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71  3_vtab_cursor sq
381e0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
381f0 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  r;.typedef struc
38200 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
38210 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b   sqlite3_module;
38220 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38230 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
38240 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
38250 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  DS: sqlite3_modu
38260 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c  le {virtual tabl
38270 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20  e module}.**.** 
38280 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20  This structure, 
38290 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64  sometimes called
382a0 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c   a "virtual tabl
382b0 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64  e module", .** d
382c0 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65  efines the imple
382d0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b  mentation of a [
382e0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
382f0 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63    .** This struc
38300 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f  ture consists mo
38310 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20  stly of methods 
38320 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
38330 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c  **.** ^A virtual
38340 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73   table module is
38350 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c   created by fill
38360 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74  ing in a persist
38370 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20  ent.** instance 
38380 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
38390 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20  e and passing a 
383a0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
383b0 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b  instance.** to [
383c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
383d0 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c  odule()] or [sql
383e0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
383f0 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68  le_v2()]..** ^Th
38400 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72  e registration r
38410 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74  emains valid unt
38420 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65  il it is replace
38430 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74  d by a different
38440 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e  .** module or un
38450 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73  til the [databas
38460 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c  e connection] cl
38470 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65  oses.  The conte
38480 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74  nt.** of this st
38490 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74  ructure must not
384a0 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74   change while it
384b0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77   is registered w
384c0 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62  ith.** any datab
384d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
384e0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
384f0 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74  3_module {.  int
38500 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
38510 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69   (*xCreate)(sqli
38520 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
38530 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
38540 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
38550 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
38560 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
38570 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
38580 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
38590 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  ;.  int (*xConne
385a0 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
385b0 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
385c0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
385d0 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
385e0 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
385f0 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
38600 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
38610 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
38620 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71  (*xBestIndex)(sq
38630 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
38640 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  b, sqlite3_index
38650 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28  _info*);.  int (
38660 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71  *xDisconnect)(sq
38670 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
38680 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73  b);.  int (*xDes
38690 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74  troy)(sqlite3_vt
386a0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
386b0 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
386c0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
386d0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
386e0 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b  sor **ppCursor);
386f0 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
38700 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
38710 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
38720 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33  xFilter)(sqlite3
38730 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69  _vtab_cursor*, i
38740 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74  nt idxNum, const
38750 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20   char *idxStr,. 
38760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
38770 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33  nt argc, sqlite3
38780 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a  _value **argv);.
38790 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73    int (*xNext)(s
387a0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
387b0 6f 72 2a 29 3b 0a 20 20