System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact f93ff25197a6aba5754fa1bd6371ddcb408f7bf4:


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 31 30 22 0a 23 64 65 66 69 6e 65 20 53  .7.10".#define S
1030: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1040: 4d 42 45 52 20 33 30 30 37 30 31 30 0a 23 64 65  MBER 3007010.#de
1050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
1060: 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 32  CE_ID      "2012
1070: 2d 30 31 2d 31 36 20 31 33 3a 32 38 3a 34 30 20  -01-16 13:28:40 
1080: 65 62 64 30 31 61 38 64 65 66 66 62 35 30 32 34  ebd01a8deffb5024
1090: 61 35 64 37 34 39 34 65 65 66 38 30 30 64 32 33  a5d7494eef800d23
10a0: 36 36 64 39 37 32 30 34 22 0a 0a 2f 2a 0a 2a 2a  66d97204"../*.**
10b0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
10c0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
10d0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
10e0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10f0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
1100: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
1110: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
1120: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
1130: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
1140: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1150: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1170: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1180: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1190: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
11a0: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
11b0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
11c0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
11d0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
11e0: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11f0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
1200: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
1210: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
1220: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
1230: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
1240: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1250: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1260: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1270: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1280: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1290: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
12a0: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
12b0: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
12c0: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
12d0: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
12e0: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12f0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1300: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
1310: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1320: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
1330: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1340: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1350: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1360: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1370: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1380: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1390: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
13a0: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
13b0: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
13c0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13d0: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
13e0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13f0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1400: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
1410: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
1420: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
1430: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
1440: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1450: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1460: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1470: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1480: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1490: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
14a0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
14b0: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
14c0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
14d0: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
14e0: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14f0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1500: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
1510: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
1520: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1530: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
1540: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1550: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1560: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1570: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1580: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1590: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
15a0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
15b0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
15c0: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
15d0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
15e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15f0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
1600: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
1610: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1620: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1630: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
1640: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1650: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1660: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1670: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1680: 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  PI SQLITE_EXTERN
1690: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
16a0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53  te3_version[];.S
16b0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16c0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69  char *sqlite3_li
16d0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  bversion(void);.
16e0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
16f0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1700: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53  ourceid(void);.S
1710: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1720: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1730: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
1740: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1750: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1760: 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74   Compilation Opt
1770: 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73  ions Diagnostics
1780: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1790: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
17a0: 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f  n_used() functio
17b0: 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31  n returns 0 or 1
17c0: 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20   .** indicating 
17d0: 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63  whether the spec
17e0: 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73  ified option was
17f0: 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20   defined at .** 
1800: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e  compile time.  ^
1810: 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66  The SQLITE_ pref
1820: 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  ix may be omitte
1830: 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f  d from the .** o
1840: 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65  ption name passe
1850: 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  d to sqlite3_com
1860: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1870: 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).  .**.** ^The 
1880: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1890: 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63  ption_get() func
18a0: 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72  tion allows iter
18b0: 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68  ating.** over th
18c0: 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e  e list of option
18d0: 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69  s that were defi
18e0: 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ned at compile t
18f0: 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e  ime by.** return
1900: 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d  ing the N-th com
1910: 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e  pile time option
1920: 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20   string.  ^If N 
1930: 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
1940: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1950: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1960: 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1970: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51  ointer.  ^The SQ
1980: 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78  LITE_ .** prefix
1990: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
19a0: 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74   any strings ret
19b0: 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  urned by .** sql
19c0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19d0: 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20  on_get()..**.** 
19e0: 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65  ^Support for the
19f0: 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63   diagnostic func
1a00: 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f  tions sqlite3_co
1a10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1a20: 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ().** and sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69  get() may be omi
1a50: 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69  tted by specifyi
1a60: 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  ng the .** [SQLI
1a70: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f  TE_OMIT_COMPILEO
1a80: 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74  PTION_DIAGS] opt
1a90: 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ion at compile t
1aa0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ime..**.** See a
1ab0: 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f  lso: SQL functio
1ac0: 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ns [sqlite_compi
1ad0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d  leoption_used()]
1ae0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f   and.** [sqlite_
1af0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b00: 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f  t()] and the [co
1b10: 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72  mpile_options pr
1b20: 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65  agma]..*/.#ifnde
1b30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f  f SQLITE_OMIT_CO
1b40: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b50: 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  S.SQLITE_API int
1b60: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1b70: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73  option_used(cons
1b80: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65  t char *zOptName
1b90: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1ba0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1bb0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1bc0: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1bd0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1be0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1bf0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1c00: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1c10: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c20: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1c30: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1c40: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1c50: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1c60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1c70: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1c80: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1c90: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1ca0: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1cb0: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1cc0: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1cd0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1ce0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1cf0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1d00: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1d10: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d20: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1d30: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1d40: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1d50: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1d60: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1d70: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1d80: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d90: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1da0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1db0: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1dc0: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1dd0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1de0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1df0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1e00: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1e10: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1e20: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1e30: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1e40: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1e50: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1e60: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1e70: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1e80: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1e90: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1ea0: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1eb0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1ec0: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1ed0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1ee0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1ef0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1f00: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1f10: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1f20: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1f30: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
1f40: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
1f50: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
1f60: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
1f70: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
1f80: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
1f90: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1fa0: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
1fb0: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
1fc0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fd0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
1fe0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1ff0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
2000: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
2010: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
2020: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2030: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2040: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2050: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2060: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2070: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2080: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2090: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
20a0: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
20b0: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
20c0: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
20d0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
20e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
20f0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
2100: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2110: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
2120: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2130: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65  UTEX].  ^(The re
2160: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2170: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2180: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2190: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
21a0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
21b0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
21c0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
21d0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
21e0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
21f0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2200: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2210: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2220: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2230: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2240: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2250: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2260: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2270: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2280: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2290: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
22a0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
22b0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22c0: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
22d0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22e0: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
22f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2300: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2310: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
2320: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
2330: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
2340: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2350: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
2360: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
2370: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
2380: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
2390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
23a0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
23b0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
23c0: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
23d0: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
23e0: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
23f0: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
2400: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
2410: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
2420: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2430: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
2440: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2450: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
2460: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
2470: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
2480: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73 20  _close()].** is 
2490: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e 20  its destructor. 
24a0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
24b0: 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  other interfaces
24c0: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
24d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
24e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
24f0: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2500: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2510: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
2520: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
2530: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
2540: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
2550: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
2560: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2570: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
2580: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2590: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
25a0: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  r Types.** KEYWO
25b0: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
25c0: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
25d0: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
25e0: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
25f0: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
2600: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
2610: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
2620: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
2630: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
2640: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
2650: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
2660: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2670: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2680: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
2690: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
26a0: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
26b0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
26c0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
26d0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
26e0: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
26f0: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
2700: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
2710: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2720: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2730: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20  ite_int64 types 
2740: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2750: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  r values.** betw
2760: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  een -92233720368
2770: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32  54775808 and +92
2780: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
2790: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54  7 inclusive.  ^T
27a0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69  he.** sqlite3_ui
27b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
27c0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  uint64 types can
27d0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
27e0: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65  alues .** betwee
27f0: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34  n 0 and +1844674
2800: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e  4073709551615 in
2810: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64  clusive..*/.#ifd
2820: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2830: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
2840: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2850: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2860: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2870: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
2880: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
2890: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
28a0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
28b0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
28c0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
28d0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
28e0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
28f0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2900: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2910: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2920: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2930: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2940: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2950: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2960: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2970: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2980: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2990: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
29a0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
29b0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
29c0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
29d0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
29e0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
29f0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2a00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2a10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2a20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2a30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2a40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2a50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2a60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2a70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2a80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2a90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2aa0: 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tion.**.** ^The 
2ab0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ac0: 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64  routine is the d
2ad0: 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
2ae0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2af0: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
2b00: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2b10: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
2b20: 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  K if the [sqlite
2b30: 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  3] object is.** 
2b40: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73  successfully des
2b50: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61  troyed and all a
2b60: 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75 72  ssociated resour
2b70: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
2b80: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ted..**.** Appli
2b90: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73 71  cations must [sq
2ba0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
2bb0: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b   finalize] all [
2bc0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2bd0: 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  nts].** and [sql
2be0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
2bf0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
2c00: 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f  OB handles] asso
2c10: 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74  ciated with.** t
2c20: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2c30: 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74  ect prior to att
2c40: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65  empting to close
2c50: 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49   the object.  ^I
2c60: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f  f.** sqlite3_clo
2c70: 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  se() is called o
2c80: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
2c90: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
2ca0: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
2cb0: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
2cc0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f 72  d statements] or
2cd0: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
2ce0: 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73   then it returns
2cf0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  .** SQLITE_BUSY.
2d00: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c 69  .**.** ^If [sqli
2d10: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
2d20: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
2d30: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
2d40: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
2d50: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
2d60: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2d70: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
2d80: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
2d90: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2da0: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  ] must be either
2db0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2dc0: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
2dd0: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
2de0: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
2df0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
2e00: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2e10: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
2e20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2e30: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
2e40: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
2e50: 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
2e60: 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68 20  e3_close() with 
2e70: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
2e80: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a 2a  rgument is a .**
2e90: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
2ea0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2eb0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
2ec0: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
2ed0: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
2ee0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2ef0: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
2f00: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
2f10: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
2f20: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
2f30: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
2f40: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
2f50: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
2f60: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
2f70: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
2f80: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
2f90: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
2fa0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
2fb0: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
2fc0: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
2fd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2fe0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
2ff0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
3000: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f  ence wrapper aro
3010: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
3020: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
3030: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
3040: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
3050: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68  nalize()],.** th
3060: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70  at allows an app
3070: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20  lication to run 
3080: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65  multiple stateme
3090: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69  nts of SQL.** wi
30a0: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
30b0: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  use a lot of C c
30c0: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode. .**.** ^The
30d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
30e0: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a  interface runs z
30f0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d  ero or more UTF-
3100: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65  8 encoded,.** se
3110: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
3120: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3130: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20  passed into its 
3140: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a  2nd argument,.**
3150: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20   in the context 
3160: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
3170: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73   connection] pas
3180: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73  sed in as its 1s
3190: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  t.** argument.  
31a0: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
31b0: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65   function of the
31c0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
31d0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
31e0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  () is not NULL, 
31f0: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b  then it is invok
3200: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75  ed for each resu
3210: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67  lt row.** coming
3220: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c   out of the eval
3230: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  uated SQL statem
3240: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20  ents.  ^The 4th 
3250: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
3260: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3270: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68   relayed through
3280: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75   to the 1st argu
3290: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  ment of each.** 
32a0: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74  callback invocat
32b0: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ion.  ^If the ca
32c0: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74  llback pointer t
32d0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
32e0: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  .** is NULL, the
32f0: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73  n no callback is
3300: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e   ever invoked an
3310: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72  d result rows ar
3320: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  e.** ignored..**
3330: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
3340: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76   occurs while ev
3350: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c  aluating the SQL
3360: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3370: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  ed into.** sqlit
3380: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20  e3_exec(), then 
3390: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
33a0: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65   current stateme
33b0: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20  nt stops and.** 
33c0: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65  subsequent state
33d0: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65  ments are skippe
33e0: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20  d.  ^If the 5th 
33f0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3400: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
3410: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
3420: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
3430: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  e is written int
3440: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
3450: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3460: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
3470: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72   passed back thr
3480: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
3490: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76  ameter..** To av
34a0: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73  oid memory leaks
34b0: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
34c0: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20  n should invoke 
34d0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
34e0: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73  .** on error mes
34f0: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74  sage strings ret
3500: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68  urned through th
3510: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3520: 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  of.** of sqlite3
3530: 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68  _exec() after th
3540: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
3550: 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e  string is no lon
3560: 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e  ger needed..** ^
3570: 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  If the 5th param
3580: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3590: 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55  exec() is not NU
35a0: 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73  LL and no errors
35b0: 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20  .** occur, then 
35c0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73  sqlite3_exec() s
35d0: 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20  ets the pointer 
35e0: 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d  in its 5th param
35f0: 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20  eter to.** NULL 
3600: 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
3610: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73  ..**.** ^If an s
3620: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3630: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
3640: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c  on-zero, the sql
3650: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72  ite3_exec().** r
3660: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53  outine returns S
3670: 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68  QLITE_ABORT with
3680: 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  out invoking the
3690: 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20   callback again 
36a0: 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72  and.** without r
36b0: 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65  unning any subse
36c0: 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d  quent SQL statem
36d0: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
36e0: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   2nd argument to
36f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3700: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  c() callback fun
3710: 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20  ction is the.** 
3720: 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
3730: 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e  s in the result.
3740: 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d    ^The 3rd argum
3750: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3760: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c  e3_exec().** cal
3770: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
3780: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3790: 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65   strings obtaine
37a0: 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20  d as if from.** 
37b0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
37c0: 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72  text()], one for
37d0: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e   each column.  ^
37e0: 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66  If an element of
37f0: 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77   a.** result row
3800: 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
3810: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
3820: 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66  string pointer f
3830: 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  or the.** sqlite
3840: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3850: 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  k is a NULL poin
3860: 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61  ter.  ^The 4th a
3870: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
3880: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3890: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
38a0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
38b0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65  s to strings whe
38c0: 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79  re each.** entry
38d0: 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20   represents the 
38e0: 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f  name of correspo
38f0: 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c  nding result col
3900: 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a  umn as obtained.
3910: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
3920: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e  _column_name()].
3930: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32  .**.** ^If the 2
3940: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
3950: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3960: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3970: 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  , a pointer.** t
3980: 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
3990: 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  g, or a pointer 
39a0: 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e  that contains on
39b0: 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e  ly whitespace an
39c0: 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d  d/or .** SQL com
39d0: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53  ments, then no S
39e0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
39f0: 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20  e evaluated and 
3a00: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
3a10: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a  is not changed..
3a20: 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f  **.** Restrictio
3a30: 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ns:.**.** <ul>.*
3a40: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
3a50: 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75  cation must insu
3a60: 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20  re that the 1st 
3a70: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3a80: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20  ite3_exec().**  
3a90: 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61      is a valid a
3aa0: 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  nd open [databas
3ab0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
3ac0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
3ad0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
3ae0: 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 20  close [database 
3af0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
3b00: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
3b10: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
3b20: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b30: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3b40: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3b50: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ning..** <li> Th
3b60: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
3b70: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  st not modify th
3b80: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
3b90: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f  text passed into
3ba0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64  .**      the 2nd
3bb0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
3bc0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3bd0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3be0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3bf0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ul>.*/.SQLITE
3c00: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
3c10: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
3c20: 2a 2c 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 20 20                  
3c40: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
3c50: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
3c60: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
3c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c80: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
3c90: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
3ca0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
3cb0: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3cc0: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
3cd0: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
3ce0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  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 20 20                  
3d10: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
3d20: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
3d30: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
3d40: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
3d50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d60: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
3d70: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
3d80: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3d90: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
3da0: 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
3db0: 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65  E_OK {error code
3dc0: 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a  } {error codes}.
3dd0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65  ** KEYWORDS: {re
3de0: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75  sult code} {resu
3df0: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
3e00: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
3e10: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
3e20: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
3e30: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
3e40: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69   shown.** here i
3e50: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
3e60: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66  ate success or f
3e70: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
3e80: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
3e90: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
3ea0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
3eb0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
3ec0: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
3ed0: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
3ee0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3ef0: 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  des],.** [sqlite
3f00: 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
3f10: 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f  ct()] [SQLITE_RO
3f20: 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20  LLBACK | result 
3f30: 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69  codes]..*/.#defi
3f40: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
3f50: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
3f60: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
3f70: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
3f80: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
3f90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3fa0: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
3fb0: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
3fc0: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
3fd0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
3fe0: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
3ff0: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
4000: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
4010: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
4020: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
4030: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
4040: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
4050: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4060: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
4070: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
4080: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
4090: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
40a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
40b0: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
40c0: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
40d0: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
40e0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
40f0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
4100: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
4110: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
4120: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
4130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
4140: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
4150: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
4160: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4170: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
4180: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
4190: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
41a0: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
41b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
41c0: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
41d0: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
41e0: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
41f0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
4200: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4210: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
4220: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
4230: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
4240: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
4250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
4260: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
4270: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
4280: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
4290: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
42a0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
42b0: 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f     12   /* Unkno
42c0: 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c  wn opcode in sql
42d0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
42e0: 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  l() */.#define S
42f0: 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20  QLITE_FULL      
4300: 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74    13   /* Insert
4310: 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75  ion failed becau
4320: 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66  se database is f
4330: 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ull */.#define S
4340: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20  QLITE_CANTOPEN  
4350: 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65    14   /* Unable
4360: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
4370: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f  efine SQLITE_PRO
4390: 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a  TOCOL    15   /*
43a0: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
43b0: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
43c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
43d0: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
43e0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
43f0: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
4400: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
4410: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
4420: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
4430: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
4440: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
4450: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
4460: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
4470: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
44a0: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
44b0: 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69  to constraint vi
44c0: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69  olation */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54  ne SQLITE_MISMAT
44e0: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61  CH    20   /* Da
44f0: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68  ta type mismatch
4500: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4510: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32  TE_MISUSE      2
4520: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75  1   /* Library u
4530: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  sed incorrectly 
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4550: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32  E_NOLFS       22
4560: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65     /* Uses OS fe
4570: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f  atures not suppo
4580: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a  rted on host */.
4590: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
45a0: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20  UTH        23   
45b0: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  /* Authorization
45c0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
45d0: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54  ne SQLITE_FORMAT
45e0: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75        24   /* Au
45f0: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65  xiliary database
4600: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f   format error */
4610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4620: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20  RANGE       25  
4630: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65   /* 2nd paramete
4640: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
4650: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a  d out of range *
4660: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4670: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20  _NOTADB      26 
4680: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64    /* File opened
4690: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64   that is not a d
46a0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
46b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
46c0: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
46d0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
46e0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
46f0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4700: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4710: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4720: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4730: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4740: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4750: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4760: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4770: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4780: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4790: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72  DS: {extended er
47a0: 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ror code} {exten
47b0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d  ded error codes}
47c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
47d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
47e0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72  ode} {extended r
47f0: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a  esult codes}.**.
4800: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4810: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4820: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4830: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4840: 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a  of 26 integer.**
4850: 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
4860: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f  sult codes].  Ho
4870: 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63  wever, experienc
4880: 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74  e has shown that
4890: 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73   many of.** thes
48a0: 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  e result codes a
48b0: 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72  re too coarse-gr
48c0: 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20  ained.  They do 
48d0: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a  not provide as.*
48e0: 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69  * much informati
48f0: 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d  on about problem
4900: 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  s as programmers
4910: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e   might like.  In
4920: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a   an effort to.**
4930: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e   address this, n
4940: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
4950: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e   SQLite (version
4960: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72   3.3.8 and later
4970: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
4980: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
4990: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
49a0: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
49b0: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
49c0: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
49d0: 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74   errors. The ext
49e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
49f0: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f  es are enabled o
4a00: 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e  r disabled.** on
4a10: 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20   a per database 
4a20: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
4a30: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
4a40: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
4a50: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20  result_codes()] 
4a60: 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20  API..**.** Some 
4a70: 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  of the available
4a80: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a90: 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65   codes are liste
4aa0: 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d  d here..** One m
4ab0: 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75  ay expect the nu
4ac0: 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64  mber of extended
4ad0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69   result codes wi
4ae0: 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20  ll be expand.** 
4af0: 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74  over time.  Soft
4b00: 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65  ware that uses e
4b10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4b20: 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65  odes should expe
4b30: 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77  ct.** to see new
4b40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e   result codes in
4b50: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
4b60: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4b70: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20  * The SQLITE_OK 
4b80: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c  result code will
4b90: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64   never be extend
4ba0: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77  ed.  It will alw
4bb0: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c  ays.** be exactl
4bc0: 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69  y zero..*/.#defi
4bd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4be0: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
4bf0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4c00: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
4c10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
4c20: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
4c30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4c40: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
4c50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
4c60: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
4c70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c80: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
4c90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
4ca0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
4cb0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4cc0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
4cd0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
4ce0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
4cf0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
4d00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4d10: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
4d20: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
4d30: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
4d40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4d50: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
4d60: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4d70: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
4dc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4dd0: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
4de0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4df0: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
4e00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4e10: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
4e20: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4e30: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
4e40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4e50: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
4e60: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4e70: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
4e80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4e90: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
4ea0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4eb0: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
4ec0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4ed0: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
4ee0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4ef0: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
4f00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f10: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
4f20: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
4f30: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
4f40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f50: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
4f60: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4f70: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
4f80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f90: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
4fa0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4fb0: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
4fc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4fd0: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
4fe0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4ff0: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
5000: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5010: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
5020: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5030: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
5040: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5050: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
5060: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5070: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
5080: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5090: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
50a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50b0: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
50c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50d0: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
50e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50f0: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
5100: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5110: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
5120: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5130: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
5140: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5150: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
5160: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
5170: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
5180: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5190: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
51a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51b0: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
51c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51d0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45  TE_CANTOPEN_NOTE
51e0: 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49  MPDIR      (SQLI
51f0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31  TE_CANTOPEN | (1
5200: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5210: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5220: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5230: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5240: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5250: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5260: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
5270: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5280: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5290: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
52a0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
52b0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
52c0: 20 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (2<<8))../*.*
52d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
52e0: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
52f0: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
5300: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
5310: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
5320: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
5330: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
5340: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
5350: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
5360: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
5370: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
5380: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5390: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
53a0: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
53b0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
53c0: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
53d0: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
53e0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
53f0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5400: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5410: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5420: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
5430: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5440: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5450: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5460: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5470: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
5480: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5490: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
54a0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
54b0: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
54c0: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
54d0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
54e0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
54f0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
5500: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
5510: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
5520: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
5530: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
5540: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
5550: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
5560: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
5570: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5580: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
5590: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
55a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
55b0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
55c0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
55d0: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* VFS on
55e0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
55f0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
5600: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
5610: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
5620: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
5630: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
5640: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
5650: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
5660: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
5670: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
5680: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
5690: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
56a0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
56b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
56c0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
56d0: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
56e0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
56f0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
5700: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
5710: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
5720: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
5730: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
5740: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
5750: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
5760: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
5770: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
5780: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
5790: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
57a0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
57b0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
57c0: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
57d0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
57e0: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
57f0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5800: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5810: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
5820: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
5830: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
5840: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5850: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5860: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
5870: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
5880: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
5890: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
58a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
58b0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
58c0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
58d0: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
58e0: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76  ly */../* Reserv
58f0: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
5900: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5910: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
5920: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
5930: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
5940: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
5950: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
5960: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
5970: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5980: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
5990: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
59a0: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
59b0: 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73  ctor of the thes
59c0: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20  e.** bit values 
59d0: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63  expressing I/O c
59e0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f  haracteristics o
59f0: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61  f the mass stora
5a00: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  ge.** device tha
5a10: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65  t holds the file
5a20: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
5a30: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
5a40: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a  * refers to..**.
5a50: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
5a60: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
5a70: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
5a80: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
5a90: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
5aa0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
5ab0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
5ac0: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
5ad0: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
5ae0: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
5af0: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
5b00: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
5b10: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
5b20: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
5b30: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
5b40: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
5b50: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
5b60: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
5b70: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
5b80: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
5b90: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
5ba0: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
5bb0: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
5bc0: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
5bd0: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
5be0: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
5bf0: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
5c00: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
5c10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
5c20: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
5c30: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
5c40: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
5c50: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
5c60: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
5c70: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
5c80: 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53  xWrite().  The S
5c90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
5ca0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
5cb0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5cc0: 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62  hat.** after reb
5cd0: 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  oot following a 
5ce0: 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c  crash or power l
5cf0: 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79  oss, the only by
5d00: 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65  tes in a.** file
5d10: 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74   that were writt
5d20: 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63  en at the applic
5d30: 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68  ation level migh
5d40: 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a  t have changed.*
5d50: 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63  * and that adjac
5d60: 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20  ent bytes, even 
5d70: 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65  bytes within the
5d80: 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65   same sector are
5d90: 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74  .** guaranteed t
5da0: 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a  o be unchanged..
5db0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5dc0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
5dd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5de0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
5df0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5e00: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
5e10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5e20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
5e40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5e50: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
5e60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5e70: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
5e80: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
5e90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ea0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
5eb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5ec0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
5ed0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5ee0: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
5ef0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
5f00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5f10: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
5f20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5f30: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
5f40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
5f50: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
5f60: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
5f70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5f80: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5f90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
5fa0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5fb0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
5fc0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
5fd0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
5fe0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
5ff0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
6000: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
6010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6020: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6030: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
6040: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
6050: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6060: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6070: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a 2f     0x00001000../
6080: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6090: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
60a0: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
60b0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
60c0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
60d0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
60e0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
60f0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6100: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6110: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6120: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6130: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6140: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6150: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6160: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6170: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6180: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6190: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
61a0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
61b0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
61c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
61d0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
61e0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
61f0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6200: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6210: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6220: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6230: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6240: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6250: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6260: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6270: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6280: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6290: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
62a0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
62b0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
62c0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
62d0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
62e0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
62f0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
6300: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
6310: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
6320: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
6330: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
6340: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
6350: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
6360: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
6370: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6380: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
6390: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
63a0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
63b0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
63c0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
63d0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
63e0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
63f0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
6400: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
6410: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
6420: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
6430: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
6440: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
6450: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
6460: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
6470: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6480: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6490: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
64a0: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
64b0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
64c0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
64d0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
64e0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
64f0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
6500: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
6510: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
6520: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
6530: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
6540: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
6550: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
6560: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
6570: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6580: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
6590: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
65a0: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
65b0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
65c0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
65d0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
65e0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
65f0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
6600: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
6610: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
6620: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
6630: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
6640: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
6650: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
6660: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
6670: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
6680: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
6690: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
66a0: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
66b0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
66c0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
66d0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
66e0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
66f0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
6700: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
6710: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
6720: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6730: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
6740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6750: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
6760: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
6770: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6780: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
6790: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
67a0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
67b0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
67c0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
67d0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
67e0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
67f0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
6800: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
6810: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
6820: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
6830: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
6840: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
6850: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
6860: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
6870: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
6880: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
6890: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
68a0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
68b0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
68c0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
68d0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
68e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
68f0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
6900: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
6910: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
6920: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
6930: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
6940: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
6950: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
6960: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
6970: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
6980: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
6990: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
69a0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
69b0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
69c0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
69d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
69e0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
69f0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
6a00: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
6a10: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
6a20: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
6a30: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
6a40: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
6a50: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
6a60: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
6a70: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
6a80: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
6a90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
6aa0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
6ab0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
6ac0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
6ad0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
6ae0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
6af0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
6b00: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
6b10: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
6b20: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
6b30: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
6b40: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
6b50: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
6b60: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
6b70: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
6b80: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
6b90: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
6ba0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
6bb0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
6bc0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
6bd0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
6be0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
6bf0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
6c00: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
6c10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
6c20: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
6c30: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
6c40: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
6c50: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
6c60: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
6c70: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
6c80: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
6c90: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
6ca0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6cb0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
6cc0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
6cd0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
6ce0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
6cf0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
6d00: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
6d10: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
6d20: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
6d30: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
6d40: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
6d50: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
6d60: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
6d70: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
6d80: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
6d90: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
6da0: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
6db0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6dc0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
6dd0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
6de0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
6df0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
6e00: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
6e10: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
6e20: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
6e30: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
6e40: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
6e50: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
6e60: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
6e70: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
6e80: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
6e90: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6ea0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
6eb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6ec0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
6ed0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6ee0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
6ef0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6f00: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
6f10: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
6f20: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
6f30: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
6f40: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
6f50: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
6f60: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
6f70: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
6f80: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
6f90: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
6fa0: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
6fb0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
6fc0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
6fd0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
6fe0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
6ff0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7000: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7010: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7020: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7030: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7040: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7050: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7060: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7070: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7080: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7090: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
70a0: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
70b0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
70c0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
70d0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
70e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
70f0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7100: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7110: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7120: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7130: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7140: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7150: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7160: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7170: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7180: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7190: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
71a0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
71b0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
71c0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
71d0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
71e0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
71f0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7200: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7210: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7220: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7230: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7240: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7250: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7260: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7270: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7280: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7290: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
72a0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
72b0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
72c0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
72d0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
72e0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
72f0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
7300: 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f  e..** A [SQLITE_
7310: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
7320: 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65  | list of opcode
7330: 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  s] less than 100
7340: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
7350: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
7360: 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73  hat define a cus
7370: 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  tom xFileControl
7380: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75   method should u
7390: 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72  se opcodes.** gr
73a0: 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74  eater than 100 t
73b0: 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74  o avoid conflict
73c0: 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  s.  VFS implemen
73d0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a  tations should.*
73e0: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
73f0: 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66  _NOTFOUND] for f
7400: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
7410: 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f  des that they do
7420: 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a   not.** recogniz
7430: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65  e..**.** The xSe
7440: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f  ctorSize() metho
7450: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65  d returns the se
7460: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65  ctor size of the
7470: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
7480: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69  underlies the fi
7490: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20  le.  The sector 
74a0: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d  size is the.** m
74b0: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61  inimum write tha
74c0: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  t can be perform
74d0: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75  ed without distu
74e0: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62  rbing.** other b
74f0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
7500: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68  .  The xDeviceCh
7510: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a  aracteristics().
7520: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
7530: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64  s a bit vector d
7540: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69  escribing behavi
7550: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e  ors of the.** un
7560: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a  derlying device:
7570: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
7580: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7590: 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69  P_ATOMIC].** <li
75a0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
75b0: 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c  ATOMIC512].** <l
75c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
75d0: 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC1K].** <l
75e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
75f0: 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC2K].** <l
7600: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7610: 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC4K].** <l
7620: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7630: 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC8K].** <l
7640: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7650: 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c  _ATOMIC16K].** <
7660: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7670: 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20  P_ATOMIC32K].** 
7680: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7690: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a  AP_ATOMIC64K].**
76a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
76b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d  CAP_SAFE_APPEND]
76c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
76d0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
76e0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  L].** </ul>.**.*
76f0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
7700: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
7710: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
7720: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
7730: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
7740: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
7750: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
7760: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
7770: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
7780: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
7790: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
77a0: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
77b0: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
77c0: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
77d0: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
77e0: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
77f0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
7800: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
7810: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
7820: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
7830: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
7840: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
7850: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
7860: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
7870: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
7880: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
7890: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
78a0: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
78b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
78c0: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
78d0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
78e0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
78f0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
7900: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
7910: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
7920: 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49  Write()..**.** I
7930: 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e  f xRead() return
7940: 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  s SQLITE_IOERR_S
7950: 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73  HORT_READ it mus
7960: 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69  t also fill.** i
7970: 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72  n the unread por
7980: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66  tions of the buf
7990: 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20  fer with zeros. 
79a0: 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66   A VFS that.** f
79b0: 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  ails to zero-fil
79c0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69  l short reads mi
79d0: 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b  ght seem to work
79e0: 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
79f0: 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66  ailure to zero-f
7a00: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
7a10: 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20  will eventually 
7a20: 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62  lead to.** datab
7a30: 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  ase corruption..
7a40: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7a50: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
7a60: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f  hods sqlite3_io_
7a70: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
7a80: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7a90: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  ds {.  int iVers
7aa0: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  ion;.  int (*xCl
7ab0: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ose)(sqlite3_fil
7ac0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  e*);.  int (*xRe
7ad0: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ad)(sqlite3_file
7ae0: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  *, void*, int iA
7af0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
7b00: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
7b10: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65  (*xWrite)(sqlite
7b20: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76  3_file*, const v
7b30: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
7b40: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
7b50: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54  fst);.  int (*xT
7b60: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33  runcate)(sqlite3
7b70: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7b80: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
7b90: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
7ba0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
7bb0: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
7bc0: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
7bd0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
7be0: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
7bf0: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
7c00: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7c10: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
7c20: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
7c30: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
7c40: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
7c50: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
7c60: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  le*, int *pResOu
7c70: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  t);.  int (*xFil
7c80: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
7c90: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
7ca0: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
7cb0: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
7cc0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7cd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
7ce0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
7cf0: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
7d00: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
7d10: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
7d20: 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f  for version 1 */
7d30: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70  .  int (*xShmMap
7d40: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7d50: 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67   int iPg, int pg
7d60: 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f  sz, int, void vo
7d70: 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74  latile**);.  int
7d80: 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c   (*xShmLock)(sql
7d90: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7da0: 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69  offset, int n, i
7db0: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69  nt flags);.  voi
7dc0: 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29  d (*xShmBarrier)
7dd0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7de0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d  .  int (*xShmUnm
7df0: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
7e00: 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61  *, int deleteFla
7e10: 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  g);.  /* Methods
7e20: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
7e30: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a   for version 2 *
7e40: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
7e50: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
7e60: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
7e70: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
7e80: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7e90: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
7ea0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
7eb0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
7ec0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
7ed0: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
7ee0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7ef0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
7f00: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7f10: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
7f20: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
7f30: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
7f40: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
7f50: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
7f60: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
7f70: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
7f80: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
7f90: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
7fa0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
7fb0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
7fc0: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
7fd0: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
7fe0: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
7ff0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
8000: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
8010: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
8020: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
8030: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
8040: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
8050: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
8060: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
8070: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
8080: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
8090: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
80a0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
80b0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
80c0: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
80d0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
80e0: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
80f0: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
8100: 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ined..**.** The 
8110: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8120: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
8130: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
8140: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
8150: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
8160: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
8170: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8180: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
8190: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
81a0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
81b0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
81c0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
81d0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
81e0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
81f0: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
8200: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
8210: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
8220: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
8230: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
8240: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
8250: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
8260: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
8270: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
8280: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
8290: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
82a0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
82b0: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
82c0: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
82d0: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
82e0: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
82f0: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
8300: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
8310: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
8320: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
8330: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
8340: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
8350: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8360: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
8370: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
8380: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
8390: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
83a0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
83b0: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
83c0: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
83d0: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
83e0: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
83f0: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
8400: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
8410: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
8420: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
8430: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
8440: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
8450: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
8460: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
8470: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8480: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
8490: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
84a0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
84b0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
84c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
84d0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
84e0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
84f0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
8500: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
8510: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8520: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
8530: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
8540: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
8550: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ation..**.** ^(T
8560: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8570: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f  _SYNC_OMITTED] o
8580: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
8590: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
85a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73  .** SQLite and s
85b0: 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73  ent to all VFSes
85c0: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63   in place of a c
85d0: 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63  all to the xSync
85e0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20   method.** when 
85f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
8600: 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41  nection has [PRA
8610: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
8620: 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a   set to OFF.)^.*
8630: 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a  * Some specializ
8640: 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68  ed VFSes need th
8650: 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64  is signal in ord
8660: 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f  er to operate co
8670: 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20  rrectly.** when 
8680: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
8690: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
86a0: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73  chronous=OFF] is
86b0: 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a   set, but most .
86c0: 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20  ** VFSes do not 
86d0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
86e0: 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65   and should sile
86f0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
8700: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c   opcode..** Appl
8710: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
8720: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
8730: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8740: 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f  ] with this.** o
8750: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
8760: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
8770: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
8780: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
8790: 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20  FSes.** that do 
87a0: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
87b0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
87c0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
87d0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
87e0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
87f0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
8800: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
8810: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
8820: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
8830: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
8840: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
8850: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
8860: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
8870: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
8880: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
8890: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
88a0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
88b0: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
88c0: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
88d0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
88e0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
88f0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
8900: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
8910: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
8920: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
8930: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
8940: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
8950: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
8960: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
8970: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
8980: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
8990: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
89a0: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
89b0: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
89c0: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
89d0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
89e0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
89f0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
8a00: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
8a10: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
8a20: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
8a30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
8a40: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
8a50: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
8a60: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
8a70: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
8a80: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
8a90: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
8aa0: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
8ab0: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
8ac0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
8ad0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
8ae0: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
8af0: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
8b00: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
8b10: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
8b20: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
8b30: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
8b40: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
8b50: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
8b60: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
8b70: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
8b80: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
8b90: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
8ba0: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
8bb0: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
8bc0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
8bd0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
8be0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
8bf0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20  TL_PERSIST_WAL] 
8c00: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8c10: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
8c20: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
8c30: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 48   [WAL | Write AH
8c40: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67  ead Log] setting
8c50: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
8c60: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20  he auxiliary.** 
8c70: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20  write ahead log 
8c80: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
8c90: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72  y files used for
8ca0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
8cb0: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f  trol.** are auto
8cc0: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
8cd0: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73  d when the lates
8ce0: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  t connection to 
8cf0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8d00: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67  closes.  Setting
8d10: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
8d20: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73  mode causes thos
8d30: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69  e files to persi
8d40: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73  st after.** clos
8d50: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74  e.  Persisting t
8d60: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66  he files is usef
8d70: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72  ul when other pr
8d80: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20  ocesses that do 
8d90: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74  not.** have writ
8da0: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20  e permission on 
8db0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f  the directory co
8dc0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74  ntaining the dat
8dd0: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a  abase file want.
8de0: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64  ** to read the d
8df0: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73  atabase file, as
8e00: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61   the WAL and sha
8e10: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
8e20: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69   must exist.** i
8e30: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20  n order for the 
8e40: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  database to be r
8e50: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f  eadable.  The fo
8e60: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
8e70: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
8e80: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
8e90: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
8ea0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
8eb0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
8ec0: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
8ed0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
8ee0: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
8ef0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
8f00: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  ble persistent.*
8f10: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20  * WAL mode.  If 
8f20: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
8f30: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
8f40: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
8f50: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41  he current.** WA
8f60: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65  L persistence se
8f70: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tting..**.** ^Th
8f80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8f90: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
8fa0: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
8fb0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
8fc0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
8fd0: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
8fe0: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
8ff0: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
9000: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
9010: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
9020: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
9030: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9040: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
9050: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
9060: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
9070: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
9080: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9090: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
90a0: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
90b0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
90c0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
90d0: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
90e0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
90f0: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
9100: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
9110: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
9120: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
9130: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
9140: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
9150: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
9160: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
9170: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
9180: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
9190: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
91a0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
91b0: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
91c0: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
91d0: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
91e0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
91f0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
9200: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
9210: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
9220: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
9230: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
9240: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
9250: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
9260: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
9270: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
9280: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
9290: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
92a0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
92b0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
92c0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
92d0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
92e0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
92f0: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
9300: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
9310: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
9320: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
9330: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
9340: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
9350: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
9360: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
9370: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
9380: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
9390: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
93a0: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
93b0: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
93c0: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
93d0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
93e0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
93f0: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
9400: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
9410: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
9420: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
9430: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
9440: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
9450: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
9460: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
9470: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
9480: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
9490: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
94a0: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
94b0: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
94c0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
94d0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
94e0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
94f0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9500: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
9510: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
9520: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
9530: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
9540: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2f  tic use only..*/
9550: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9560: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
9570: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
9580: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
9590: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
95a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
95b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
95c0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
95d0: 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
95e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
95f0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
9600: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
9610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
9620: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
9630: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
9640: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
9650: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
9660: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
9670: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
9680: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
9690: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
96a0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
96b0: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
96c0: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
96d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
96e0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
96f0: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
9700: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9710: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
9720: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
9730: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
9740: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
9750: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
9760: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
9770: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
9780: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
9790: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
97a0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
97b0: 20 31 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   13../*.** CAPI3
97c0: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
97d0: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  e.**.** The mute
97e0: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
97f0: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
9800: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
9810: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
9820: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
9830: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
9840: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
9850: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
9860: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
9870: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
9880: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
9890: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
98a0: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
98b0: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
98c0: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
98d0: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
98e0: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
98f0: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
9900: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
9910: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
9920: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
9930: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
9940: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
9950: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
9960: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
9970: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
9980: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
9990: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
99a0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
99b0: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
99c0: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
99d0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
99e0: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
99f0: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
9a00: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
9a10: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
9a20: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
9a30: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
9a40: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
9a50: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
9a60: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
9a70: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
9a80: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
9a90: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
9aa0: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
9ab0: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
9ac0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
9ad0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
9ae0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
9af0: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
9b00: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
9b10: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
9b20: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
9b30: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
9b40: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
9b50: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
9b60: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
9b70: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
9b80: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
9b90: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
9ba0: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
9bb0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
9bc0: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
9bd0: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
9be0: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
9bf0: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
9c00: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
9c10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
9c20: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
9c30: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
9c40: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
9c50: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
9c60: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
9c70: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
9c80: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
9c90: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
9ca0: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
9cb0: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
9cc0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
9cd0: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
9ce0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
9cf0: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
9d00: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
9d10: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
9d20: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
9d30: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
9d40: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
9d50: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
9d60: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
9d70: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
9d80: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
9d90: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
9da0: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
9db0: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
9dc0: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
9dd0: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
9de0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
9df0: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
9e00: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
9e10: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
9e20: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
9e30: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
9e40: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
9e50: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
9e60: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
9e70: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
9e80: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
9e90: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
9ea0: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
9eb0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
9ec0: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
9ed0: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
9ee0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
9ef0: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
9f00: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
9f10: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
9f20: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
9f30: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
9f40: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
9f50: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
9f60: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
9f70: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
9f80: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73  dules..**.** [[s
9f90: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
9fa0: 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  ]].** ^SQLite gu
9fb0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
9fc0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
9fd0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
9fe0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
9ff0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
a000: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
a010: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
a020: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
a030: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
a040: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
a050: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
a060: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
a070: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
a080: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
a090: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
a0a0: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
a0b0: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
a0c0: 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72  ** 11 alphanumer
a0d0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
a0e0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
a0f0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
a100: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
a110: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
a120: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
a130: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
a140: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
a150: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
a160: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
a170: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
a180: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
a190: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
a1a0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
a1b0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
a1c0: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
a1d0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
a1e0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
a1f0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
a200: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
a210: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
a220: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
a230: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
a240: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
a250: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
a260: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
a270: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
a280: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
a290: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
a2a0: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
a2b0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
a2c0: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
a2d0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
a2e0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
a2f0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
a300: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
a310: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
a320: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
a330: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
a340: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
a350: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
a360: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
a370: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
a380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
a390: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
a3a0: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
a3b0: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
a3c0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
a3d0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
a3e0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
a3f0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
a400: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
a410: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
a420: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
a430: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
a440: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
a450: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
a460: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
a470: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
a480: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
a490: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
a4a0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
a4b0: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
a4c0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
a4d0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
a4e0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
a4f0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
a500: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
a510: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
a520: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
a530: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
a540: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
a550: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
a560: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
a570: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
a580: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
a590: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
a5a0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
a5b0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
a5c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
a5d0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
a5e0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
a5f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
a600: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
a610: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
a620: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a630: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
a640: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
a650: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
a660: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
a670: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
a680: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
a690: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
a6a0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
a6b0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
a6c0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
a6d0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
a6e0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
a6f0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
a700: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
a710: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
a720: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
a730: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
a740: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
a750: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
a760: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
a770: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
a780: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
a790: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
a7a0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
a7b0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
a7c0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
a7d0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
a7e0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
a7f0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
a800: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
a810: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
a820: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
a830: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
a840: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
a850: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
a860: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
a870: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
a880: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
a890: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
a8a0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
a8b0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
a8c0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
a8d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
a8e0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
a8f0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
a900: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
a910: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
a920: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
a930: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
a940: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
a950: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
a960: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
a970: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
a980: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
a990: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
a9a0: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
a9b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
a9c0: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
a9d0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
a9e0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
a9f0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
aa00: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
aa10: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
aa20: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
aa30: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
aa40: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
aa50: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
aa60: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
aa70: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
aa80: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
aa90: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
aaa0: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
aab0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
aac0: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
aad0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
aae0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
aaf0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
ab00: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
ab10: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
ab20: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
ab30: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
ab40: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
ab50: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
ab60: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
ab70: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
ab80: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
ab90: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
aba0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
abb0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
abc0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
abd0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
abe0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
abf0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
ac00: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
ac10: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
ac20: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
ac30: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
ac40: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
ac50: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
ac60: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
ac70: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
ac80: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
ac90: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
aca0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
acb0: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
acc0: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
acd0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
ace0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
acf0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
ad00: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
ad10: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
ad20: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
ad30: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
ad40: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
ad50: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
ad60: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
ad70: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
ad80: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
ad90: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
ada0: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
adb0: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b  en call..**.** [
adc0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63  [sqlite3_vfs.xAc
add0: 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66  cess]].** ^The f
ade0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
adf0: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
ae00: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
ae10: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
ae20: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
ae30: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
ae40: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
ae50: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
ae60: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
ae70: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
ae80: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
ae90: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
aea0: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
aeb0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
aec0: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
aed0: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
aee0: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
aef0: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
af00: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  * ^SQLite will a
af10: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
af20: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
af30: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
af40: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
af50: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
af60: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
af70: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
af80: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
af90: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
afa0: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
afb0: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
afc0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
afd0: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
afe0: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
aff0: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
b000: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
b010: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
b020: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
b030: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
b040: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
b050: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
b060: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
b070: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
b080: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
b090: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
b0a0: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
b0b0: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
b0c0: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
b0d0: 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  , xCurrentTime()
b0e0: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
b0f0: 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74  meInt64().** int
b100: 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20  erfaces are not 
b110: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
b120: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
b130: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
b140: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
b150: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
b160: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
b170: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
b180: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
b190: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
b1a0: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
b1b0: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
b1c0: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
b1d0: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
b1e0: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
b1f0: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
b200: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
b210: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
b220: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
b230: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
b240: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
b250: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
b260: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
b270: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
b280: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
b290: 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54    ^The xCurrentT
b2a0: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
b2b0: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
b2c0: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
b2d0: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
b2e0: 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20   and time as.** 
b2f0: 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
b300: 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20   value..** ^The 
b310: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
b320: 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  4() method retur
b330: 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65  ns, as an intege
b340: 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a  r, the Julian.**
b350: 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74   Day Number mult
b360: 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30  iplied by 864000
b370: 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f  00 (the number o
b380: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69  f milliseconds i
b390: 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20  n .** a 24-hour 
b3a0: 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69  day).  .** ^SQLi
b3b0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
b3c0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
b3d0: 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65  4() method to ge
b3e0: 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  t the current.**
b3f0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69   date and time i
b400: 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73  f that method is
b410: 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69   available (if i
b420: 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20  Version is 2 or 
b430: 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20  .** greater and 
b440: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
b450: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
b460: 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20  ) and will fall 
b470: 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72  back.** to xCurr
b480: 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75  entTime() if xCu
b490: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
b4a0: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
b4b0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74  .**.** ^The xSet
b4c0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47  SystemCall(), xG
b4d0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
b4e0: 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43  and xNestSystemC
b4f0: 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73  all() interfaces
b500: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64  .** are not used
b510: 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63   by the SQLite c
b520: 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69  ore.  These opti
b530: 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  onal interfaces 
b540: 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
b550: 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f  by some VFSes to
b560: 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74   facilitate test
b570: 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63  ing of the VFS c
b580: 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69  ode. By overridi
b590: 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61  ng .** system ca
b5a0: 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f  lls with functio
b5b0: 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e  ns under its con
b5c0: 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f  trol, a test pro
b5d0: 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75  gram can.** simu
b5e0: 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20  late faults and 
b5f0: 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73  error conditions
b600: 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65   that would othe
b610: 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75  rwise be difficu
b620: 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69  lt.** or impossi
b630: 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20  ble to induce.  
b640: 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65  The set of syste
b650: 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e  m calls that can
b660: 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a   be overridden.*
b670: 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  * varies from on
b680: 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72  e VFS to another
b690: 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76  , and from one v
b6a0: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61  ersion of the sa
b6b0: 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a  me VFS to the.**
b6c0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
b6d0: 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68  ions that use th
b6e0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
b6f0: 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20  ust be prepared 
b700: 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c  for any.** or al
b710: 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72  l of these inter
b720: 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c  faces to be NULL
b730: 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65   or for their be
b740: 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65  havior to change
b750: 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c  .** from one rel
b760: 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74  ease to the next
b770: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
b780: 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74  must not attempt
b790: 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e   to access.** an
b7a0: 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f  y of these metho
b7b0: 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69  ds if the iVersi
b7c0: 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73  on of the VFS is
b7d0: 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f   less than 3..*/
b7e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
b7f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
b800: 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66  te3_vfs;.typedef
b810: 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
b820: 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69  syscall_ptr)(voi
b830: 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  d);.struct sqlit
b840: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
b850: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
b860: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
b870: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
b880: 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f  (currently 3) */
b890: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
b8a0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
b8b0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
b8c0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
b8d0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
b8e0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
b8f0: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
b900: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
b910: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
b920: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
b930: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
b940: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
b950: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
b960: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
b970: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
b980: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
b990: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
b9a0: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
b9b0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
b9c0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
b9d0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
b9e0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
b9f0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
ba00: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
ba10: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
ba20: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
ba30: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
ba40: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
ba50: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ba60: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
ba70: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
ba80: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
ba90: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
baa0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
bab0: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
bac0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
bad0: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
bae0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
baf0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
bb00: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
bb10: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
bb20: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
bb30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
bb40: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
bb50: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
bb60: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
bb70: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
bb80: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
bb90: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
bba0: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
bbb0: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
bbc0: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
bbd0: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
bbe0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
bbf0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
bc00: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
bc10: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
bc20: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
bc30: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
bc40: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
bc50: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
bc60: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
bc70: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
bc80: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
bc90: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
bca0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
bcb0: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
bcc0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
bcd0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
bce0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
bcf0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
bd00: 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69  object.  ** defi
bd10: 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74  nition.  Those t
bd20: 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61  hat follow are a
bd30: 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20  dded in version 
bd40: 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a  2 or later.  */.
bd50: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
bd60: 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74  TimeInt64)(sqlit
bd70: 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33  e3_vfs*, sqlite3
bd80: 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20  _int64*);.  /*. 
bd90: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
bda0: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
bdb0: 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66  sions 1 and 2 of
bdc0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
bdd0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f  object..  ** Tho
bde0: 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72  se below are for
bdf0: 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67   version 3 and g
be00: 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69  reater..  */.  i
be10: 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43  nt (*xSetSystemC
be20: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
be30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
be40: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79  Name, sqlite3_sy
be50: 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71  scall_ptr);.  sq
be60: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
be70: 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61  r (*xGetSystemCa
be80: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
be90: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
bea0: 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68  ame);.  const ch
beb0: 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65  ar *(*xNextSyste
bec0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
bed0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
bee0: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20  *zName);.  /*.  
bef0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
bf00: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
bf10: 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33  ions 1 through 3
bf20: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
bf30: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
bf40: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
bf50: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69  e appended in fi
bf60: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  gure versions.  
bf70: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
bf80: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
bf90: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
bfa0: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20  this happens. . 
bfb0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
bfc0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
bfd0: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
bfe0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
bff0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
c000: 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
c010: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
c020: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
c030: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
c040: 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
c050: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
c060: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
c070: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
c080: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
c090: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
c0a0: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a   looking for..**
c0b0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
c0c0: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
c0d0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
c0e0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
c0f0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
c100: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68   exists..** With
c110: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
c120: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
c130: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
c140: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
c150: 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f  he named directo
c160: 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  ry is both reada
c170: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
c180: 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f  .** (in other wo
c190: 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61  rds, if files ca
c1a0: 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f  n be added, remo
c1b0: 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64  ved, and renamed
c1c0: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64   within.** the d
c1d0: 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68  irectory)..** Th
c1e0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
c1f0: 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61  READWRITE consta
c200: 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  nt is currently 
c210: 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65  used only by the
c220: 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  .** [temp_store_
c230: 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
c240: 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63  ], though this c
c250: 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61  ould change in a
c260: 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
c270: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
c280: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
c290: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
c2a0: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
c2b0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
c2c0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
c2d0: 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
c2e0: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e  _ACCESS_READ con
c2f0: 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72  stant is.** curr
c300: 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68  ently unused, th
c310: 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65  ough it might be
c320: 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72   used in a futur
c330: 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
c340: 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
c350: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
c360: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
c370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
c380: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20  SS_READWRITE 1  
c390: 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47   /* Used by PRAG
c3a0: 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  MA temp_store_di
c3b0: 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69  rectory */.#defi
c3c0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
c3d0: 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f  _READ      2   /
c3e0: 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  * Unused */../*.
c3f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
c400: 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c  gs for the xShmL
c410: 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ock VFS method.*
c420: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
c430: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  er constants def
c440: 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20  ine the various 
c450: 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f  locking operatio
c460: 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79  ns.** allowed by
c470: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   the xShmLock me
c480: 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  thod of [sqlite3
c490: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54  _io_methods].  T
c4a0: 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
c4b0: 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67  are the only leg
c4c0: 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  al combinations 
c4d0: 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a  of flags to the.
c4e0: 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  ** xShmLock meth
c4f0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
c500: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
c510: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
c520: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
c530: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
c540: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
c550: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
c560: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
c570: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
c580: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
c590: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
c5a0: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
c5b0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
c5c0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  </ul>.**.** When
c5d0: 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20   unlocking, the 
c5e0: 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45  same SHARED or E
c5f0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75  XCLUSIVE flag mu
c600: 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61  st be supplied a
c610: 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e  s.** was given n
c620: 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
c630: 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a  ing lock.  .**.*
c640: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
c650: 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69  ethod can transi
c660: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c  tion between unl
c670: 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44  ocked and SHARED
c680: 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75   or.** between u
c690: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c  nlocked and EXCL
c6a0: 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f  USIVE.  It canno
c6b0: 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  t transition bet
c6c0: 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61  ween SHARED.** a
c6d0: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f  nd EXCLUSIVE..*/
c6e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c6f0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  SHM_UNLOCK      
c700: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
c710: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20  E_SHM_LOCK      
c720: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
c730: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20  ITE_SHM_SHARED  
c740: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
c750: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
c760: 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20  IVE    8../*.** 
c770: 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75  CAPI3REF: Maximu
c780: 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78  m xShmLock index
c790: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
c7a0: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73  ock method on [s
c7b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
c7c0: 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65  s] may use value
c7d0: 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61  s.** between 0 a
c7e0: 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f  nd this upper bo
c7f0: 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73  und as its "offs
c800: 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  et" argument..**
c810: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
c820: 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65   will never atte
c830: 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f  mpt to acquire o
c840: 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c  r release a.** l
c850: 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74  ock outside of t
c860: 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65  his range.*/.#de
c870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
c880: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a  NLOCK        8..
c890: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c8a0: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
c8b0: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
c8c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
c8d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
c8e0: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
c8f0: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
c900: 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
c910: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c920: 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
c930: 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
c940: 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
c950: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
c960: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c970: 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
c980: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
c990: 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
c9a0: 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
c9b0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
c9c0: 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
c9d0: 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
c9e0: 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
c9f0: 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
ca00: 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
ca10: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
ca20: 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
ca30: 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
ca40: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
ca50: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ca60: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
ca70: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
ca80: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
ca90: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
caa0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
cab0: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
cac0: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
cad0: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
cae0: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
caf0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
cb00: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
cb10: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
cb20: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
cb30: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
cb40: 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
cb50: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
cb60: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
cb70: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
cb80: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
cb90: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
cba0: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
cbb0: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
cbc0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
cbd0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
cbe0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
cbf0: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
cc00: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
cc10: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
cc20: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
cc30: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
cc40: 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
cc50: 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
cc60: 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
cc70: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
cc80: 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
cc90: 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
cca0: 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
ccb0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ccc0: 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
ccd0: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
cce0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
ccf0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
cd00: 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
cd10: 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
cd20: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
cd30: 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
cd40: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
cd50: 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
cd60: 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
cd70: 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
cd80: 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
cd90: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
cda0: 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
cdb0: 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
cdc0: 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
cdd0: 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
cde0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
cdf0: 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
ce00: 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
ce10: 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
ce20: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
ce30: 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
ce40: 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
ce50: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
ce60: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
ce70: 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
ce80: 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
ce90: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
cea0: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
ceb0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
cec0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
ced0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
cee0: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
cef0: 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
cf00: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
cf10: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
cf20: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
cf30: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
cf40: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
cf50: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
cf60: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
cf70: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
cf80: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
cf90: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
cfa0: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
cfb0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
cfc0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
cfd0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
cfe0: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
cff0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
d000: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
d010: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
d020: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
d030: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
d040: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
d050: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
d060: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
d070: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
d080: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
d090: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
d0a0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d0b0: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
d0c0: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
d0d0: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
d0e0: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
d0f0: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
d100: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
d110: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
d120: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
d130: 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
d140: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
d150: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
d160: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
d170: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
d180: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
d190: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
d1a0: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
d1b0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
d1c0: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
d1d0: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
d1e0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
d1f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d200: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
d210: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
d220: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
d230: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
d240: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
d250: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
d260: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
d270: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
d280: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
d290: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d2a0: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
d2b0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
d2c0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
d2d0: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
d2e0: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
d2f0: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
d300: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
d310: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
d320: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
d330: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
d340: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
d350: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
d360: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
d370: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
d380: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
d390: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
d3a0: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
d3b0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d3c0: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
d3d0: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
d3e0: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
d3f0: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
d400: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
d410: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
d420: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
d430: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
d440: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
d450: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
d460: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
d470: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
d480: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
d490: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
d4a0: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
d4b0: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
d4c0: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
d4d0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
d4e0: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
d4f0: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
d500: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
d510: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
d520: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
d530: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
d540: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
d550: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
d560: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
d570: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
d580: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
d590: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
d5a0: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
d5b0: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
d5c0: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
d5d0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
d5e0: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
d5f0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d600: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
d610: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
d620: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
d630: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
d640: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
d650: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
d660: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
d670: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
d680: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
d690: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
d6a0: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
d6b0: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
d6c0: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
d6d0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
d6e0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
d6f0: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
d700: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
d710: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
d720: 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
d730: 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
d740: 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
d750: 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
d760: 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
d770: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
d780: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
d790: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
d7a0: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
d7b0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
d7c0: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
d7d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
d7e0: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
d7f0: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
d800: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
d810: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
d820: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
d830: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
d840: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
d850: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
d860: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
d870: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
d880: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
d890: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
d8a0: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
d8b0: 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  re..*/.SQLITE_AP
d8c0: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  I int sqlite3_in
d8d0: 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
d8e0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
d8f0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d900: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
d910: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  I int sqlite3_os
d920: 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c  _init(void);.SQL
d930: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
d940: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
d950: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
d960: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
d970: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
d980: 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
d990: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
d9a0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
d9b0: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
d9c0: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
d9d0: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
d9e0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
d9f0: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
da00: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
da10: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
da20: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
da30: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
da40: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
da50: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
da60: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
da70: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
da80: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
da90: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
daa0: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
dab0: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
dac0: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
dad0: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
dae0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
daf0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
db00: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
db10: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
db20: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
db30: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
db40: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
db50: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
db60: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
db70: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
db80: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
db90: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
dba0: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
dbb0: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
dbc0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
dbd0: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
dbe0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
dbf0: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
dc00: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
dc10: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
dc20: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
dc30: 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
dc40: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
dc50: 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
dc60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
dc70: 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
dc80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
dc90: 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
dca0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
dcb0: 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
dcc0: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
dcd0: 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
dce0: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
dcf0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
dd00: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
dd10: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
dd20: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
dd30: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
dd40: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
dd50: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
dd60: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
dd70: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
dd80: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
dd90: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
dda0: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
ddb0: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
ddc0: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
ddd0: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
dde0: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
ddf0: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
de00: 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
de10: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
de20: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
de30: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
de40: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
de50: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
de60: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
de70: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
de80: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
de90: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
dea0: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
deb0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
dec0: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
ded0: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
dee0: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
def0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
df00: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
df10: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
df20: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
df30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
df40: 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
df50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
df60: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
df70: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
df80: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
df90: 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
dfa0: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
dfb0: 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
dfc0: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
dfd0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
dfe0: 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
dff0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
e000: 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
e010: 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
e020: 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
e030: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
e040: 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
e050: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e060: 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
e070: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
e080: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
e090: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
e0a0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
e0b0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
e0c0: 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
e0d0: 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
e0e0: 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
e0f0: 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
e100: 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
e110: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e120: 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
e130: 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
e140: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
e150: 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
e160: 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
e170: 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
e180: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
e190: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
e1a0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
e1b0: 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
e1c0: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
e1d0: 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
e1e0: 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ssful..*/.SQLITE
e1f0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
e200: 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
e210: 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
e220: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
e230: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
e240: 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
e250: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
e260: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
e270: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
e280: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
e290: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
e2a0: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
e2b0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
e2c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
e2d0: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
e2e0: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
e2f0: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
e300: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
e310: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
e320: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
e330: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
e340: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
e350: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
e360: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
e370: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
e380: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
e390: 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
e3a0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
e3b0: 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
e3c0: 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
e3d0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
e3e0: 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
e3f0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
e400: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
e410: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
e420: 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
e430: 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
e440: 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
e450: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
e460: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
e470: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
e480: 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
e490: 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
e4a0: 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
e4b0: 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
e4c0: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
e4d0: 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
e4e0: 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
e4f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
e500: 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
e510: 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
e520: 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
e530: 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
e540: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
e550: 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
e560: 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
e570: 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
e580: 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
e590: 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
e5a0: 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
e5b0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
e5c0: 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
e5d0: 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
e5e0: 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
e5f0: 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
e600: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
e610: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
e620: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
e630: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
e640: 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
e650: 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
e660: 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
e670: 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
e680: 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
e690: 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
e6a0: 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
e6b0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
e6c0: 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
e6d0: 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
e6e0: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
e6f0: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
e700: 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
e710: 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
e720: 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
e730: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
e740: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
e750: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
e760: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
e770: 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
e780: 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
e790: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
e7a0: 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
e7b0: 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
e7c0: 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
e7d0: 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
e7e0: 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
e7f0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
e800: 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
e810: 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
e820: 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
e830: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
e840: 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
e850: 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
e860: 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
e870: 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
e880: 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
e890: 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
e8a0: 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
e8b0: 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
e8c0: 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
e8d0: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
e8e0: 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
e8f0: 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
e900: 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
e910: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
e920: 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
e930: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
e940: 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
e950: 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
e960: 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
e970: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
e980: 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
e990: 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
e9a0: 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
e9b0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
e9c0: 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
e9d0: 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
e9e0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
e9f0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
ea00: 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
ea10: 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
ea20: 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
ea30: 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
ea40: 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
ea50: 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
ea60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
ea70: 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
ea80: 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
ea90: 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
eaa0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28  ry allocator.  (
eab0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
eac0: 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
ead0: 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
eae0: 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
eaf0: 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
eb00: 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
eb10: 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
eb20: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
eb30: 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
eb40: 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
eb50: 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
eb60: 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
eb70: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
eb80: 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
eb90: 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
eba0: 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
ebb0: 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
ebc0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
ebd0: 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
ebe0: 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
ebf0: 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
ec00: 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
ec10: 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
ec20: 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
ec30: 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
ec40: 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
ec50: 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
ec60: 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
ec70: 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
ec80: 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
ec90: 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
eca0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
ecb0: 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
ecc0: 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
ecd0: 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
ece0: 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
ecf0: 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
ed00: 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
ed10: 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
ed20: 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
ed30: 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
ed40: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
ed50: 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
ed60: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
ed70: 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
ed80: 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
ed90: 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
eda0: 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
edb0: 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
edc0: 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
edd0: 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
ede0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
edf0: 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
ee00: 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
ee10: 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
ee20: 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
ee30: 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
ee40: 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
ee50: 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
ee60: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
ee70: 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
ee80: 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
ee90: 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
eea0: 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
eeb0: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
eec0: 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
eed0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
eee0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
eef0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
ef00: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
ef10: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
ef20: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
ef30: 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
ef40: 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
ef50: 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
ef60: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
ef70: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
ef80: 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
ef90: 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
efa0: 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
efb0: 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
efc0: 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
efd0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
efe0: 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
eff0: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
f000: 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
f010: 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
f020: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
f030: 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
f040: 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
f050: 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
f060: 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
f070: 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
f080: 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
f090: 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
f0a0: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
f0b0: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
f0c0: 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
f0d0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
f0e0: 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
f0f0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
f100: 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
f110: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
f120: 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
f130: 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
f140: 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
f150: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
f160: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
f170: 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
f180: 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
f190: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
f1a0: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
f1b0: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
f1c0: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
f1d0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
f1e0: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
f1f0: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
f200: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f210: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
f220: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
f230: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
f240: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f250: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
f260: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
f270: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
f280: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
f290: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f2a0: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
f2b0: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
f2c0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
f2d0: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
f2e0: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
f2f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
f300: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
f310: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
f320: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
f330: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
f340: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
f350: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
f360: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
f370: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
f380: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
f390: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f3a0: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
f3b0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
f3c0: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
f3d0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
f3e0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f3f0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
f400: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
f410: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
f420: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
f430: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
f440: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
f450: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
f460: 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
f470: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
f480: 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
f490: 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
f4a0: 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
f4b0: 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
f4c0: 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
f4d0: 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
f4e0: 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
f4f0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
f500: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
f510: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
f520: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
f530: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
f540: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
f550: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
f560: 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
f570: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
f580: 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
f590: 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
f5a0: 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
f5b0: 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
f5c0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
f5d0: 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
f5e0: 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
f5f0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
f600: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
f610: 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
f620: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f630: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
f640: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
f650: 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
f660: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
f670: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
f680: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
f690: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
f6a0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
f6b0: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
f6c0: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
f6d0: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
f6e0: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
f6f0: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
f700: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
f710: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
f720: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
f730: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
f740: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
f750: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
f760: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
f770: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
f780: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
f790: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
f7a0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
f7b0: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
f7c0: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
f7d0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
f7e0: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
f7f0: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
f800: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
f810: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
f820: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
f830: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
f840: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
f850: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
f860: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
f870: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
f880: 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
f890: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
f8a0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
f8b0: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
f8c0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
f8d0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
f8e0: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
f8f0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
f900: 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
f910: 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
f920: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
f930: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f940: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
f950: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
f960: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
f970: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
f980: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
f990: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f9a0: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
f9b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
f9c0: 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
f9d0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
f9e0: 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
f9f0: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
fa00: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
fa10: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
fa20: 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
fa30: 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
fa40: 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
fa50: 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
fa60: 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
fa70: 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
fa80: 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
fa90: 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
faa0: 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
fab0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fac0: 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
fad0: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
fae0: 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
faf0: 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
fb00: 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
fb10: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
fb20: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
fb30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
fb40: 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
fb50: 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
fb60: 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
fb70: 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
fb80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
fb90: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
fba0: 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
fbb0: 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
fbc0: 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
fbd0: 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
fbe0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fbf0: 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
fc00: 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
fc10: 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
fc20: 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
fc30: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
fc40: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
fc50: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
fc60: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
fc70: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
fc80: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
fc90: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
fca0: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
fcb0: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
fcc0: 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
fcd0: 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
fce0: 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
fcf0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
fd00: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
fd10: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
fd20: 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
fd30: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
fd40: 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
fd50: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
fd60: 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
fd70: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
fd80: 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
fd90: 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
fda0: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
fdb0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
fdc0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
fdd0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
fde0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
fdf0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
fe00: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
fe10: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
fe20: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
fe30: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
fe40: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
fe50: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
fe60: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
fe70: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
fe80: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
fe90: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
fea0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
feb0: 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
fec0: 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
fed0: 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
fee0: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
fef0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
ff00: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
ff10: 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
ff20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ff30: 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
ff40: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
ff50: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
ff60: 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
ff70: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
ff80: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
ff90: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
ffa0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
ffb0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
ffc0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
ffd0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
ffe0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
fff0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
10000 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  e.  The [sqlite3
10010 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
10020 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
10030 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
10040 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
10050 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10060 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
10070 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
10080 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
10090 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
100a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
100b0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
100c0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
100d0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
100e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
100f0 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
10100 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
10110 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
10120 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
10130 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
10140 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
10150 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
10160 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
10170 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
10180 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
10190 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
101a0 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
101b0 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20   a .** boolean, 
101c0 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
101d0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
101e0 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
101f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a  ry allocation .*
10200 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  * statistics. ^(
10210 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
10220 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
10230 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20  s are disabled, 
10240 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  the .** followin
10250 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
10260 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
10270 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
10280 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
10290 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
102a0 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
102b0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
102c0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
102d0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
102e0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
102f0 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
10300 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
10310 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
10320 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
10330 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
10340 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
10350 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
10360 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
10370 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
10380 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
10390 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
103a0 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
103b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
103c0 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
103d0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
103e0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
103f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
10400 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
10410 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
10420 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
10430 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
10440 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
10450 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
10460 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
10470 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
10480 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
10490 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
104a0 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  ts:  A pointer a
104b0 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
104c0 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
104d0 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
104e0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
104f0 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
10500 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
10510 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
10520 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
10530 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
10540 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
10550 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
10560 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
10570 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
10580 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
10590 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73   16..** The firs
105a0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
105b0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
105c0 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
105d0 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
105e0 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
105f0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
10600 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
10610 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74  e no more than t
10620 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65  wo scratch buffe
10630 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20  rs per thread.  
10640 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62  So.** N should b
10650 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74  e set to twice t
10660 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
10670 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
10680 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  reads..** ^SQLit
10690 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
106a0 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62  uire a scratch b
106b0 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
106c0 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
106d0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
106e0 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53  page size. ^If S
106f0 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
10700 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
10710 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
10720 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
10730 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
10740 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10750 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
10760 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10770 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
10780 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
10790 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a  ry needed.</dd>.
107a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
107b0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
107c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
107d0 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
107e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
107f0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
10800 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
10810 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
10820 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
10830 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
10840 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
10850 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
10860 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
10870 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
10880 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
10890 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
108a0 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  ed if an applica
108b0 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
108c0 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
108d0 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
108e0 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ed using the SQL
108f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
10900 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  E2 option..** Th
10910 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
10920 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
10930 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
10940 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
10950 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
10960 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
10970 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
10980 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
10990 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
109a0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
109b0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
109c0 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
109d0 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
109e0 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
109f0 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
10a00 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
10a10 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
10a20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
10a30 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
10a40 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
10a50 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
10a60 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
10a70 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
10a80 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
10a90 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
10aa0 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
10ab0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
10ac0 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
10ad0 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
10ae0 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
10af0 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
10b00 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
10b10 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
10b20 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
10b30 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
10b40 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
10b50 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
10b60 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10b70 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
10b80 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
10b90 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
10ba0 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
10bb0 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
10bc0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
10bd0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
10be0 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
10bf0 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
10c00 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
10c10 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
10c20 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
10c30 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
10c40 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
10c50 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
10c60 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
10c70 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10c80 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
10c90 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
10ca0 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
10cb0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
10cc0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
10cd0 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
10ce0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
10cf0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
10d00 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
10d10 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
10d20 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
10d30 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
10d40 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
10d50 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
10d60 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
10d70 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
10d80 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
10d90 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62  location needs b
10da0 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
10db0 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b  ided.** for by [
10dc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
10dd0 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49  RATCH] and [SQLI
10de0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
10df0 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61  CHE]..** There a
10e00 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
10e10 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  ts: An 8-byte al
10e20 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
10e30 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
10e40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
10e50 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
10e60 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
10e70 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
10e80 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
10e90 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
10ea0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
10eb0 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
10ec0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
10ed0 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
10ee0 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
10ef0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
10f00 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
10f10 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
10f20 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
10f30 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
10f40 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
10f50 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
10f60 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
10f70 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
10f80 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
10f90 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
10fa0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
10fb0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
10fc0 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
10fd0 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
10fe0 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
10ff0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
11000 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
11010 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
11020 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
11030 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
11040 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
11050 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
11060 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
11070 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
11080 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
11090 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
110a0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
110b0 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
110c0 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
110d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
110e0 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
110f0 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
11100 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
11110 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
11120 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
11130 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
11140 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11150 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
11160 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
11170 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
11180 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
11190 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
111a0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
111b0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
111c0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
111d0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
111e0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
111f0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
11200 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
11210 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
11220 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
11230 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
11240 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
11250 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
11260 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
11270 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
11280 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
11290 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
112a0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
112b0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
112c0 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
112d0 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
112e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
112f0 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
11300 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
11310 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
11320 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
11330 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
11340 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
11350 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
11360 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
11370 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
11380 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
11390 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
113a0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
113b0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
113c0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
113d0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
113e0 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
113f0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
11400 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
11410 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
11420 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11430 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
11440 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11450 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
11460 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
11470 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
11480 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
11490 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
114a0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
114b0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
114c0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
114d0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
114e0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
114f0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
11500 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
11510 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
11520 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
11530 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
11540 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
11550 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
11560 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
11570 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
11580 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
11590 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
115a0 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
115b0 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
115c0 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
115d0 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
115e0 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
115f0 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
11600 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11610 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
11620 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11630 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11640 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11650 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
11660 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
11670 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
11680 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
11690 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
116a0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
116b0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
116c0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
116d0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
116e0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
116f0 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
11700 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
11710 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11720 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
11730 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
11740 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
11750 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
11760 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
11770 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
11780 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
11790 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  e the default.**
117a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
117b0 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61  on for the looka
117c0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
117d0 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a  cator on each.**
117e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
117f0 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72  ction].  The fir
11800 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
11810 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
11820 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
11830 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
11840 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
11850 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
11860 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
11870 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
11880 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68  nection.)^  ^(Th
11890 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
118a0 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74  he.** <i>default
118b0 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
118c0 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
118d0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
118e0 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20  IDE].** verb to 
118f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
11900 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
11910 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
11920 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
11930 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
11940 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
11950 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
11960 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11970 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
11980 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11990 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
119a0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
119b0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
119c0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
119d0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
119e0 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
119f0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
11a00 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
11a10 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20  bject specifies 
11a20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
11a30 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
11a40 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
11a50 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69  tation.)^  ^SQLi
11a60 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
11a70 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74  of the.** object
11a80 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72   and uses it for
11a90 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
11aa0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c  ry allocations.<
11ab0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11ac0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
11ad0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
11ae0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
11af0 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
11b00 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
11b10 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
11b20 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
11b30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
11b40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
11b50 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
11b60 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
11b70 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
11b80 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
11b90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
11ba0 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
11bb0 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
11bc0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11bd0 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
11be0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
11bf0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
11c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
11c10 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
11c20 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
11c30 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
11c40 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
11c50 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
11c60 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
11c70 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
11c80 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
11c90 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
11ca0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
11cb0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
11cc0 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
11cd0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
11ce0 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
11cf0 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
11d00 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
11d10 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
11d20 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
11d30 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
11d40 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
11d50 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
11d60 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
11d70 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
11d80 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
11d90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
11da0 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
11db0 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
11dc0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
11dd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
11de0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
11df0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
11e00 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
11e10 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
11e20 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
11e30 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
11e40 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
11e50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
11e60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
11e70 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
11e80 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
11e90 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
11ea0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
11eb0 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
11ec0 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
11ed0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
11ee0 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
11ef0 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
11f00 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
11f10 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
11f20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
11f30 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
11f40 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
11f50 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
11f60 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
11f70 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
11f80 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
11f90 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
11fa0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
11fb0 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
11fc0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
11fd0 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
11fe0 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
11ff0 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
12000 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
12010 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
12020 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
12030 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
12040 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12050 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
12060 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
12070 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70  .** <dd> This op
12080 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12090 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
120a0 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e  type int. If non
120b0 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55  -zero, then.** U
120c0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
120d0 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e  lobally enabled.
120e0 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
120f0 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  r is zero, then 
12100 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20  URI handling.** 
12110 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
12120 62 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e  bled. If URI han
12130 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
12140 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  y enabled, all f
12150 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73  ilenames.** pass
12160 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
12170 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
12180 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71  _open_v2()], [sq
12190 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
121a0 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
121b0 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
121c0 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
121d0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
121e0 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
121f0 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
12200 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
12210 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
12220 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
12230 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
12240 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
12250 64 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62  d. If it is glob
12260 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
12270 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
12280 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
12290 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
122a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
122b0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
122c0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
122d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
122e0 70 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c  pened. By defaul
122f0 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
12300 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
12310 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
12320 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
12330 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
12340 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
12350 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
12360 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
12370 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ed..**.** [[SQLI
12380 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
12390 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
123a0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
123b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
123c0 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
123d0 51 4c 49 54 45 5f 43 4f 4e 46 4e 49 47 5f 47 45  QLITE_CONFNIG_GE
123e0 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
123f0 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
12400 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
12410 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
12420 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
12430 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
12440 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
12450 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
12460 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
12470 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ps..** </dl>.*/.
12480 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12490 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
124a0 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
124b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
124c0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
124d0 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
124e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
124f0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
12500 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
12510 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12520 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
12530 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
12540 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12550 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
12560 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
12570 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
12580 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12590 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
125a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
125b0 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
125c0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
125d0 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
125e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
125f0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
12600 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
12610 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
12620 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12630 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
12640 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
12650 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
12660 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12670 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
12680 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
12690 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
126a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
126b0 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
126c0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
126d0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
126e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
126f0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
12700 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
12710 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
12720 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
12730 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
12740 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
12750 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
12760 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
12770 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
12780 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
12790 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
127a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
127b0 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
127c0 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
127d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
127e0 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
127f0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
12800 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12810 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
12820 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
12830 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
12840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
12850 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
12860 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
12870 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
12880 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
12890 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
128a0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
128b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
128c0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
128d0 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
128e0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
128f0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
12900 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
12910 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
12920 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
12930 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
12940 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
12950 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
12960 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12970 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
12980 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
12990 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
129a0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
129b0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
129c0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
129d0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
129e0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
129f0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
12a00 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
12a10 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
12a20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12a30 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
12a40 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
12a50 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
12a60 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
12a70 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
12a80 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
12a90 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
12aa0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
12ab0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
12ac0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
12ad0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
12ae0 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
12af0 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
12b00 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
12b10 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
12b20 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
12b30 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
12b40 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
12b50 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
12b60 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
12b70 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
12b80 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
12b90 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
12ba0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
12bb0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
12bc0 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
12bd0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
12be0 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
12bf0 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
12c00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12c10 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
12c20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
12c30 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
12c40 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
12c50 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
12c60 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
12c70 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
12c80 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
12c90 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
12ca0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
12cb0 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
12cc0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
12cd0 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
12ce0 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
12cf0 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
12d00 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
12d10 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
12d20 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
12d30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
12d40 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
12d50 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
12d60 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
12d70 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
12d80 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
12d90 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
12da0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
12db0 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
12dc0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
12dd0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
12de0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
12df0 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
12e00 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
12e10 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
12e20 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
12e30 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
12e40 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
12e50 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
12e60 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
12e70 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
12e80 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
12e90 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
12ea0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
12eb0 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
12ec0 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
12ed0 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
12ee0 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
12ef0 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
12f00 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
12f10 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
12f20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
12f30 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
12f40 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
12f50 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
12f60 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
12f70 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
12f80 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
12f90 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
12fa0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
12fb0 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
12fc0 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
12fd0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
12fe0 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
12ff0 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
13000 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
13010 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
13020 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
13030 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
13040 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
13050 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
13060 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
13070 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
13080 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
13090 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
130a0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
130b0 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
130c0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
130d0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
130e0 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
130f0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
13100 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
13110 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
13120 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
13130 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
13140 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
13150 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
13160 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
13170 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
13180 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13190 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
131a0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
131b0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
131c0 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
131d0 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
131e0 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
131f0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
13200 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
13210 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
13220 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
13230 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
13240 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
13250 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
13260 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
13270 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
13280 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
13290 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
132a0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
132b0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
132c0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
132d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
132e0 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
132f0 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
13300 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
13310 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
13320 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
13330 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
13340 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
13350 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
13360 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
13370 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
13380 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
13390 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
133a0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
133b0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
133c0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
133d0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
133e0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
133f0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
13400 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
13410 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
13420 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
13430 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
13440 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
13450 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
13460 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
13470 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
13480 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
13490 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
134a0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
134b0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
134c0 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
134d0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
134e0 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
134f0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
13500 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
13510 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
13520 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
13530 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
13540 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
13550 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
13560 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
13570 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
13580 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
13590 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
135a0 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20         1001  /* 
135b0 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
135c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
135d0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
135e0 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f  FKEY     1002  /
135f0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
13600 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
13610 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
13620 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69  GGER  1003  /* i
13630 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
13640 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
13650 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
13660 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
13670 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  odes.**.** ^The 
13680 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
13690 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
136a0 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
136b0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
136c0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
136d0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
136e0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
136f0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
13700 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
13710 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
13720 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
13730 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
13740 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
13750 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
13760 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
13770 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
13780 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
13790 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
137a0 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
137b0 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
137c0 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
137d0 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
137e0 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
137f0 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
13800 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
13810 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
13820 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
13830 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
13840 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
13850 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
13860 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
13870 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
13880 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
13890 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
138a0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
138b0 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
138c0 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
138d0 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
138e0 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
138f0 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
13900 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
13910 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
13920 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
13930 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
13940 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
13950 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
13960 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
13970 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
13980 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
13990 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
139a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
139b0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
139c0 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20  gument.  ^As of 
139d0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
139e0 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69  .7.7, this routi
139f0 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74  nes.** records t
13a00 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72  he last insert r
13a10 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64  owid of both ord
13a20 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64  inary tables and
13a30 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
13a40 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63  ]..** ^If no suc
13a50 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
13a60 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
13a70 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20  ccurred on that 
13a80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13a90 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74  ion, zero is ret
13aa0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  urned..**.** ^(I
13ab0 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
13ac0 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
13ad0 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
13ae0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
13af0 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
13b00 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
13b10 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
13b20 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
13b30 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
13b40 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
13b50 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
13b60 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
13b70 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
13b80 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
13b90 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
13ba0 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
13bb0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
13bc0 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
13bd0 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
13be0 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
13bf0 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
13c00 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
13c10 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
13c20 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
13c30 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
13c40 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
13c50 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
13c60 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
13c70 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
13c80 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
13c90 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
13ca0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
13cb0 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
13cc0 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
13cd0 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
13ce0 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
13cf0 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
13d00 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
13d10 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
13d20 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
13d30 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
13d40 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
13d50 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
13d60 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
13d70 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
13d80 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
13d90 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
13da0 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
13db0 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
13dc0 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
13dd0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
13de0 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
13df0 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
13e00 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
13e10 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
13e20 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
13e30 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
13e40 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
13e50 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
13e60 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
13e70 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
13e80 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
13e90 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
13ea0 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
13eb0 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
13ec0 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
13ed0 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
13ee0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
13ef0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
13f00 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
13f10 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
13f20 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
13f30 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
13f40 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
13f50 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
13f60 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
13f70 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
13f80 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
13f90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
13fa0 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
13fb0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
13fc0 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
13fd0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
13fe0 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
13ff0 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
14000 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
14010 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
14020 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
14030 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
14040 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
14050 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
14060 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
14070 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
14080 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
14090 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
140a0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
140b0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
140c0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
140d0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
140e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
140f0 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
14100 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
14110 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
14120 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
14130 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
14140 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
14150 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
14160 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
14170 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
14180 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
14190 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
141a0 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
141b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
141c0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
141d0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
141e0 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63  ter..** ^(Only c
141f0 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20  hanges that are 
14200 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69  directly specifi
14210 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52  ed by the [INSER
14220 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a  T], [UPDATE],.**
14230 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
14240 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74  tement are count
14250 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63  ed.  Auxiliary c
14260 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
14270 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20  .** triggers or 
14280 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
14290 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  ions] are not co
142a0 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65  unted.)^ Use the
142b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
142c0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
142d0 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74  nction to find t
142e0 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
142f0 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e  of changes.** in
14300 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
14310 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
14320 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b  rs and foreign k
14330 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  ey actions..**.*
14340 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  * ^Changes to a 
14350 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69  view that are si
14360 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49  mulated by an [I
14370 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
14380 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  r].** are not co
14390 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61  unted.  Only rea
143a0 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20  l table changes 
143b0 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
143c0 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e  ** ^(A "row chan
143d0 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
143e0 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
143f0 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
14400 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
14410 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
14420 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
14430 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
14440 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
14450 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
14460 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   of [REPLACE] co
14470 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
14480 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
14490 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
144a0 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d  ng, [DROP TABLE]
144b0 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65  , or by any othe
144c0 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20  r.** mechanisms 
144d0 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
144e0 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
144f0 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  es.)^.**.** A "t
14500 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
14510 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
14520 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
14530 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
14540 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
14550 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49  of a [CREATE TRI
14560 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e  GGER | trigger].
14570 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74   .** Most SQL st
14580 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
14590 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64  evaluated outsid
145a0 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72  e of any trigger
145b0 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22  .  This is the "
145c0 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72  top level".** tr
145d0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20  igger context.  
145e0 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72  If a trigger fir
145f0 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  es from the top 
14600 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20  level, a.** new 
14610 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20  trigger context 
14620 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74  is entered for t
14630 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74  he duration of t
14640 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67  hat one.** trigg
14650 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73  er.  Subtriggers
14660 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65   create subconte
14670 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75  xts for their du
14680 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ration..**.** ^C
14690 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
146a0 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
146b0 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
146c0 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
146d0 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
146e0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
146f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
14700 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
14710 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
14720 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
14730 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
14740 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
14750 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
14760 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
14770 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
14780 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
14790 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20  .** ^Thus, when 
147a0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
147b0 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
147c0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
147d0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
147e0 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
147f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
14800 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
14810 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
14820 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
14830 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
14840 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64  ^(Within the bod
14850 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a  y of a trigger,.
14860 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ** the sqlite3_c
14870 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
14880 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ce can be called
14890 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
148a0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
148b0 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
148c0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
148d0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
148e0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
148f0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
14900 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73  he body of the s
14910 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20  ame trigger..** 
14920 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d  However, the num
14930 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65  ber returned doe
14940 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
14950 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20  anges.** caused 
14960 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73  by subtriggers s
14970 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20  ince those have 
14980 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78  their own contex
14990 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
149a0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
149b0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
149c0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
149d0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
149e0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
149f0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
14a00 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
14a10 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
14a20 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
14a30 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
14a40 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
14a50 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
14a60 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
14a70 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
14a80 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
14a90 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
14aa0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
14ab0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
14ac0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
14ad0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
14ae0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
14af0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
14b00 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
14b10 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
14b20 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
14b30 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
14b40 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
14b50 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53  s caused by [INS
14b60 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45  ERT],.** [UPDATE
14b70 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
14b80 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
14b90 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
14ba0 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65  nection] was ope
14bb0 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f  ned..** ^(The co
14bc0 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
14bd0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
14be0 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73  anges() includes
14bf0 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20   all changes.** 
14c00 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45  from all [CREATE
14c10 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
14c20 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  er] contexts and
14c30 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
14c40 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
14c50 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
14c60 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
14c70 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
14c80 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
14c90 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
14ca0 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
14cb0 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
14cc0 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
14cd0 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
14ce0 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
14cf0 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
14d00 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
14d10 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
14d20 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
14d30 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
14d40 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
14d50 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
14d60 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
14d70 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
14d80 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
14d90 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
14da0 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  )^.** ^The sqlit
14db0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
14dc0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e  () function coun
14dd0 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  ts the changes a
14de0 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65  s soon as.** the
14df0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
14e00 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
14e10 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
14e20 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
14e30 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  le.** is passed 
14e40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
14e50 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
14e60 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
14e70 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
14e80 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
14e90 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
14ea0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
14eb0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
14ec0 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
14ed0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
14ee0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
14ef0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
14f00 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
14f10 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
14f20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14f30 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
14f40 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
14f50 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
14f60 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
14f70 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
14f80 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
14f90 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
14fa0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
14fb0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
14fc0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
14fd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14fe0 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
14ff0 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
15000 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  y.**.** ^This fu
15010 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
15020 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
15030 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
15040 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
15050 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
15060 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
15070 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
15080 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
15090 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
150a0 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
150b0 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
150c0 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
150d0 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
150e0 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
150f0 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
15100 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
15110 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
15120 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74  ** ^It is safe t
15130 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
15140 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
15150 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
15160 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
15170 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
15180 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
15190 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
151a0 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
151b0 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
151c0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
151d0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
151e0 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
151f0 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
15200 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
15210 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
15220 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
15230 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20  *.** ^If an SQL 
15240 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
15250 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
15260 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
15270 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
15280 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
15290 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
152a0 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
152b0 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
152c0 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
152d0 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
152e0 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
152f0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20  ..**.** ^An SQL 
15300 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
15310 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
15320 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
15330 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
15340 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75   ^If the interru
15350 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
15360 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
15370 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
15380 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
15390 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
153a0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
153b0 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
153c0 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
153d0 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
153e0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
153f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
15400 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
15410 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63  call is in effec
15420 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72  t until all curr
15430 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a  ently running.**
15440 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
15450 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
15460 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c  nection] D compl
15470 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53  ete.  ^Any new S
15480 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
15490 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
154a0 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
154b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
154c0 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
154d0 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
154e0 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
154f0 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
15500 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
15510 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
15520 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
15530 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
15540 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e  rrupt() call.  ^
15550 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
15560 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
15570 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
15580 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
15590 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
155a0 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
155b0 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
155c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
155d0 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  pt()..** ^A call
155e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
155f0 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
15600 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
15610 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
15620 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
15630 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
15640 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
15650 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
15660 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
15670 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
15680 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
15690 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
156a0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  **.** If the dat
156b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
156c0 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
156d0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
156e0 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e  ()].** is runnin
156f0 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67  g then bad thing
15700 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61  s will likely ha
15710 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ppen..*/.SQLITE_
15720 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
15730 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
15740 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
15750 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
15760 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
15770 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
15780 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
15790 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
157a0 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
157b0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
157c0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
157d0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
157e0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
157f0 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
15800 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
15810 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
15820 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
15830 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
15840 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
15850 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
15860 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
15870 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
15880 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
15890 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
158a0 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
158b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
158c0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
158d0 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
158e0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
158f0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
15900 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
15910 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
15920 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
15930 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
15940 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
15950 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
15960 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
15970 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
15980 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
15990 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
159a0 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
159b0 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
159c0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
159d0 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
159e0 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
159f0 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
15a00 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
15a10 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
15a20 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
15a30 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
15a40 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
15a50 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
15a60 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
15a70 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
15a80 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
15a90 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
15aa0 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
15ab0 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
15ac0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
15ad0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
15ae0 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
15af0 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
15b00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
15b10 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
15b20 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
15b30 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
15b40 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
15b50 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
15b60 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
15b70 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
15b80 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
15b90 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
15ba0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
15bb0 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
15bc0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
15bd0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
15be0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
15bf0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
15c00 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
15c10 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
15c20 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
15c30 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
15c40 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
15c50 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
15c60 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
15c70 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
15c80 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
15c90 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
15ca0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
15cb0 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
15cc0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
15cd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
15ce0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
15cf0 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
15d00 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
15d10 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
15d20 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
15d30 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
15d40 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
15d50 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
15d60 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
15d70 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
15d80 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
15d90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
15da0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
15db0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
15dc0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
15dd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
15de0 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
15df0 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
15e00 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
15e10 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
15e20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
15e30 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20  SY Errors.**.** 
15e40 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
15e50 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
15e60 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
15e70 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  t be invoked whe
15e80 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
15e90 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
15ea0 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
15eb0 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  able that anothe
15ec0 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
15ed0 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
15ee0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
15ef0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
15f00 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
15f10 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
15f20 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
15f30 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  KED].** is retur
15f40 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
15f50 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
15f60 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
15f70 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
15f80 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
15f90 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
15fa0 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
15fb0 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
15fc0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
15fd0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
15fe0 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
15ff0 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
16000 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
16010 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
16020 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
16030 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
16040 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
16050 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
16060 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
16070 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
16080 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
16090 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
160a0 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
160b0 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
160c0 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
160d0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
160e0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
160f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
16100 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
16110 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
16120 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
16130 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
16140 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
16150 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
16160 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
16170 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
16180 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
16190 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
161a0 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
161b0 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
161c0 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
161d0 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
161e0 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
161f0 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
16200 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
16210 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
16220 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
16230 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
16240 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
16250 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
16260 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66   contention. ^If
16270 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
16280 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
16290 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
162a0 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
162b0 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
162c0 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
162d0 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
162e0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72  LITE_BUSY].** or
162f0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
16300 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20  LOCKED] instead 
16310 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
16320 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
16330 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
16340 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
16350 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
16360 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
16370 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
16380 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
16390 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
163a0 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
163b0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
163c0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
163d0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
163e0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
163f0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
16400 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
16410 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
16420 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
16430 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
16440 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
16450 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
16460 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
16470 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
16480 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
16490 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
164a0 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
164b0 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
164c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
164d0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
164e0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
164f0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
16500 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
16510 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
16520 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
16530 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
16540 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
16550 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
16560 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
16570 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
16580 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
16590 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
165a0 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
165b0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
165c0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
165d0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  LL..**.** ^The [
165e0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
165f0 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
16600 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
16610 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
16620 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
16630 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
16640 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
16650 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
16660 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
16670 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
16680 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
16690 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
166a0 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
166b0 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
166c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
166d0 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
166e0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
166f0 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
16700 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
16710 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
16720 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
16730 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
16740 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
16750 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
16760 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20  eaders.  ^If it 
16770 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
16780 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
16790 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
167a0 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
167b0 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
167c0 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
167d0 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
167e0 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
167f0 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
16800 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
16810 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
16820 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
16830 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
16840 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54  RR_BLOCKED].  ^T
16850 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
16860 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
16870 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
16880 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
16890 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
168a0 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
168b0 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
168c0 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
168d0 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
168e0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
168f0 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
16900 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
16910 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
16920 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
16930 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  portant..**.** ^
16940 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
16950 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
16960 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
16970 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
16980 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16990 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
169a0 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
169b0 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
169c0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
169d0 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
169e0 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
169f0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
16a00 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73  t()].** will als
16a10 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74  o set or clear t
16a20 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
16a30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
16a40 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
16a50 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
16a60 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
16a70 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
16a80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
16a90 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
16aa0 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79  sy handler.  Any
16ab0 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
16ac0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
16ad0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
16ae0 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
16af0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
16b00 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
16b10 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
16b20 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
16b30 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
16b40 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
16b50 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  dler..*/.SQLITE_
16b60 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
16b70 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
16b80 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
16b90 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
16ba0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16bb0 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
16bc0 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  meout.**.** ^Thi
16bd0 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
16be0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
16bf0 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
16c00 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
16c10 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
16c20 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
16c30 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
16c40 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
16c50 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
16c60 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
16c70 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
16c80 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
16c90 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
16ca0 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
16cb0 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
16cc0 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
16cd0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
16ce0 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
16cf0 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
16d00 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
16d10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
16d20 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
16d30 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
16d40 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
16d50 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  CKED]..**.** ^Ca
16d60 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
16d70 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
16d80 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
16d90 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
16da0 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
16db0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
16dc0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
16dd0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
16de0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
16df0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
16e00 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
16e10 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
16e20 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
16e30 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
16e40 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
16e50 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
16e60 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
16e70 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
16e80 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
16e90 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
16ea0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
16eb0 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
16ec0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
16ed0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
16ee0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
16ef0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
16f00 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
16f10 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
16f20 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
16f30 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
16f40 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
16f50 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
16f60 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
16f70 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
16f80 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
16f90 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
16fa0 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
16fb0 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
16fc0 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
16fd0 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
16fe0 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
16ff0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
17000 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
17010 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
17020 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
17030 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
17040 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
17050 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
17060 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
17070 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
17080 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
17090 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
170a0 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
170b0 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
170c0 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
170d0 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
170e0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
170f0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
17100 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
17110 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
17120 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
17130 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
17140 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
17150 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
17160 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
17170 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
17180 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
17190 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
171a0 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
171b0 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
171c0 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
171d0 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
171e0 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
171f0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
17200 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
17210 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
17220 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
17230 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
17240 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
17250 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
17260 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
17270 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
17280 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
17290 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
172a0 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
172b0 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
172c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
172d0 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
172e0 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
172f0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
17300 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
17310 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
17320 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
17330 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
17340 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
17350 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
17360 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
17370 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
17380 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
17390 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
173a0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
173b0 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
173c0 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
173d0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
173e0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
173f0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
17400 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
17410 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
17420 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
17430 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
17440 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
17450 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
17460 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
17470 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
17480 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
17490 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
174a0 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
174b0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
174c0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
174d0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
174e0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
174f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
17500 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
17510 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
17520 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
17530 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
17540 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
17550 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
17560 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
17570 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
17580 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
17590 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
175a0 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
175b0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
175c0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
175d0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
175e0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
175f0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
17600 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
17610 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
17620 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
17630 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
17640 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
17650 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
17660 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
17670 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
17680 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
17690 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
176a0 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
176b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
176c0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
176d0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
176e0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
176f0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
17700 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
17710 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
17720 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
17730 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
17740 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
17750 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
17760 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
17770 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
17780 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
17790 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
177a0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
177b0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
177c0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
177d0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
177e0 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
177f0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
17800 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
17810 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
17820 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
17830 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
17840 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
17850 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
17860 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
17870 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
17880 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
17890 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
178a0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
178b0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
178c0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
178d0 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
178e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
178f0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
17900 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
17910 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
17920 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
17930 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
17940 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
17950 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
17960 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
17970 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
17980 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
17990 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
179a0 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
179b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
179c0 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
179d0 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
179e0 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
179f0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
17a00 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
17a10 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
17a20 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
17a30 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
17a40 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
17a50 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
17a60 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
17a70 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
17a80 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
17a90 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
17aa0 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
17ab0 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
17ac0 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
17ad0 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
17ae0 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
17af0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
17b00 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
17b10 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
17b20 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
17b30 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
17b40 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
17b50 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
17b60 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51  errmsg()]..*/.SQ
17b70 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
17b80 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
17b90 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
17ba0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
17bb0 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
17bc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
17bd0 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
17be0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
17bf0 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
17c00 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
17c10 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
17c20 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
17c30 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
17c40 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
17c50 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
17c60 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
17c70 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
17c80 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
17c90 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
17ca0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
17cb0 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
17cc0 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
17cd0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
17ce0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
17cf0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
17d00 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
17d10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
17d20 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
17d30 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
17d40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
17d50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
17d60 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
17d70 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
17d80 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
17d90 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
17da0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
17db0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
17dc0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
17dd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
17de0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
17df0 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
17e00 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
17e10 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
17e20 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
17e30 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
17e40 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
17e50 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
17e60 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
17e70 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
17e80 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
17e90 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
17ea0 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
17eb0 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
17ec0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
17ed0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
17ee0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
17ef0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
17f00 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
17f10 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
17f20 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
17f30 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
17f40 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
17f50 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
17f60 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
17f70 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
17f80 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
17f90 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
17fa0 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
17fb0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17fc0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
17fd0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
17fe0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
17ff0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
18000 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
18010 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
18020 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
18030 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
18040 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
18050 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
18060 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
18070 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
18080 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
18090 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
180a0 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
180b0 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
180c0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
180d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
180e0 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
180f0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
18100 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
18110 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
18120 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
18130 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
18140 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
18150 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
18160 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
18170 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
18180 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
18190 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
181a0 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
181b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
181c0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
181d0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
181e0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
181f0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
18200 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
18210 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
18220 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
18230 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
18240 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
18250 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
18260 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
18270 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
18280 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
18290 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
182a0 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
182b0 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
182c0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
182d0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
182e0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
182f0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
18300 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
18310 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
18320 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
18330 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
18340 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
18350 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
18360 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
18370 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
18380 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
18390 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
183a0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
183b0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
183c0 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
183d0 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
183e0 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
183f0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
18400 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
18410 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
18420 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
18430 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
18440 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
18450 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
18460 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
18470 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
18480 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
18490 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
184a0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
184b0 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
184c0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
184d0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
184e0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
184f0 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
18500 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
18510 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
18520 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
18530 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
18540 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
18550 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
18560 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
18570 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
18580 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
18590 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
185a0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
185b0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
185c0 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
185d0 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
185e0 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
185f0 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
18600 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
18610 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
18620 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
18630 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
18640 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
18650 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
18660 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
18670 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
18680 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
18690 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
186a0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
186b0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
186c0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
186d0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
186e0 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
186f0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
18700 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
18710 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
18720 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
18730 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
18740 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
18750 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
18760 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
18770 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
18780 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
18790 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
187a0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
187b0 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
187c0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
187d0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
187e0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
187f0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
18800 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
18810 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
18820 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
18830 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
18840 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
18850 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
18860 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
18870 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
18880 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
18890 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
188a0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
188b0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
188c0 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
188d0 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
188e0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
188f0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
18900 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
18910 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
18920 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
18930 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
18940 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
18950 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
18960 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
18970 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
18980 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
18990 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
189a0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
189b0 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
189c0 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
189d0 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
189e0 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
189f0 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
18a00 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
18a10 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
18a20 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
18a30 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
18a40 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
18a50 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
18a60 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
18a70 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
18a80 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
18a90 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
18aa0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
18ab0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
18ac0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
18ad0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
18ae0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
18af0 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
18b00 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
18b10 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
18b20 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
18b30 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
18b40 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
18b50 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
18b60 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
18b70 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
18b80 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
18b90 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
18ba0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
18bb0 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
18bc0 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
18bd0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
18be0 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
18bf0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
18c00 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
18c10 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
18c20 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
18c30 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
18c40 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
18c50 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
18c60 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
18c70 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
18c80 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
18c90 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
18ca0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
18cb0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
18cc0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
18cd0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
18ce0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
18cf0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
18d00 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49  , va_list);.SQLI
18d10 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
18d20 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
18d30 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
18d40 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54  ar*, ...);.SQLIT
18d50 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
18d60 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
18d70 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
18d80 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
18d90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18da0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
18db0 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
18dc0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
18dd0 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
18de0 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
18df0 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
18e00 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
18e10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
18e20 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
18e30 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
18e40 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
18e50 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
18e60 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
18e70 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
18e80 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
18e90 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
18ea0 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
18eb0 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
18ec0 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
18ed0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
18ee0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
18ef0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
18f00 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
18f10 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
18f20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
18f30 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
18f40 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
18f50 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
18f60 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
18f70 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
18f80 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
18f90 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
18fa0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
18fb0 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
18fc0 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
18fd0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
18fe0 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
18ff0 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
19000 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
19010 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
19020 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  nter..**.** ^Cal
19030 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
19040 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
19050 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
19060 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
19070 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
19080 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
19090 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
190a0 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
190b0 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
190c0 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
190d0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
190e0 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
190f0 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
19100 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
19110 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
19120 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
19130 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
19140 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
19150 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
19160 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
19170 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
19180 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
19190 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
191a0 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
191b0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
191c0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
191d0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
191e0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
191f0 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
19200 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
19210 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
19220 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
19230 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
19240 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
19250 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
19260 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
19270 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
19280 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
19290 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
192a0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
192b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
192c0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
192d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
192e0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
192f0 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
19300 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
19310 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
19320 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
19330 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
19340 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
19350 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
19360 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
19370 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
19380 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
19390 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66  er.)^ ^ If the f
193a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
193b0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
193c0 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
193d0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
193e0 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
193f0 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
19400 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
19410 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
19420 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
19430 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
19440 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
19450 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
19460 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
19470 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
19480 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
19490 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
194a0 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
194b0 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
194c0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
194d0 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
194e0 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
194f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
19500 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
19510 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
19520 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
19530 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
19540 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
19550 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
19560 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
19570 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
19580 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
19590 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
195a0 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
195b0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
195c0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
195d0 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
195e0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
195f0 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
19600 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
19610 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
19620 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
19630 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
19640 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
19650 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
19660 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
19670 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
19680 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
19690 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
196a0 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
196b0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
196c0 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
196d0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
196e0 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
196f0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
19700 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
19710 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
19720 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
19730 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
19740 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
19750 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
19760 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
19770 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
19780 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
19790 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
197a0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
197b0 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
197c0 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
197d0 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
197e0 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
197f0 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
19800 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
19810 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
19820 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
19830 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
19840 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
19850 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
19860 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
19870 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
19880 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
19890 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
198a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e  d..**.** The Win
198b0 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
198c0 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a  e layer calls.**
198d0 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
198e0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
198f0 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
19900 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
19910 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
19920 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
19930 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
19940 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
19950 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
19960 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
19970 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
19980 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
19990 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
199a0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61  ocation errors a
199b0 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
199c0 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70  .** they are rep
199d0 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
199e0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
199f0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
19a00 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
19a10 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
19a20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
19a30 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
19a40 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
19a50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
19a60 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
19a70 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
19a80 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
19a90 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
19aa0 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
19ab0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
19ac0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
19ad0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
19ae0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
19af0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
19b00 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
19b10 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
19b20 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
19b30 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
19b40 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
19b50 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
19b60 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
19b70 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
19b80 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
19b90 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
19ba0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
19bb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
19bc0 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45  loc(int);.SQLITE
19bd0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
19be0 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
19bf0 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
19c00 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
19c10 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
19c20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
19c30 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
19c40 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
19c50 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
19c60 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
19c70 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
19c80 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
19c90 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
19ca0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
19cb0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
19cc0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
19cd0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
19ce0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
19cf0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
19d00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
19d10 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
19d20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
19d30 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
19d40 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
19d50 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
19d60 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
19d70 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
19d80 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
19d90 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
19da0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
19db0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
19dc0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
19dd0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
19de0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
19df0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
19e00 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
19e10 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
19e20 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
19e30 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
19e40 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
19e50 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
19e60 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
19e70 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
19e80 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
19e90 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
19ea0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
19eb0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
19ec0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
19ed0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
19ee0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
19ef0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
19f00 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
19f10 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
19f20 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
19f30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
19f40 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
19f50 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
19f60 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
19f70 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
19f80 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
19f90 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
19fa0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
19fb0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
19fc0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
19fd0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
19fe0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
19ff0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1a000 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1a010 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1a020 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1a030 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1a040 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1a050 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  eset..*/.SQLITE_
1a060 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1a070 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1a080 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c  _used(void);.SQL
1a090 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1a0a0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1a0b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
1a0c0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
1a0d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a0e0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
1a0f0 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
1a100 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
1a110 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
1a120 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
1a130 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
1a140 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
1a150 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
1a160 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
1a170 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
1a180 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
1a190 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
1a1a0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
1a1b0 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
1a1c0 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
1a1d0 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
1a1e0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
1a1f0 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
1a200 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
1a210 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
1a220 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
1a230 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
1a240 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
1a250 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
1a260 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
1a270 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
1a280 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1a290 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
1a2a0 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
1a2b0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
1a2c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1a2d0 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
1a2e0 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
1a2f0 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
1a300 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
1a310 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
1a320 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
1a330 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
1a340 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
1a350 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
1a360 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
1a370 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1a380 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
1a390 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  On all subsequen
1a3a0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74  t invocations, t
1a3b0 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
1a3c0 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
1a3d0 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
1a3e0 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
1a3f0 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
1a400 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
1a410 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
1a420 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1a430 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
1a440 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
1a450 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
1a460 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
1a470 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
1a480 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
1a490 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1a4a0 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
1a4b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1a4c0 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
1a4d0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1a4e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
1a4f0 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
1a500 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
1a510 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
1a520 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1a530 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
1a540 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
1a550 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
1a560 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1a570 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1a580 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
1a590 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
1a5a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1a5b0 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
1a5c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1a5d0 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
1a5e0 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
1a5f0 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
1a600 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
1a610 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
1a620 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
1a630 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
1a640 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
1a650 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1a660 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
1a670 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
1a680 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
1a690 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
1a6a0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
1a6b0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
1a6c0 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
1a6d0 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
1a6e0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
1a6f0 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
1a700 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
1a710 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
1a720 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
1a730 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
1a740 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
1a750 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
1a760 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
1a770 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
1a780 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
1a790 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
1a7a0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
1a7b0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1a7c0 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
1a7d0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1a7e0 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
1a7f0 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
1a800 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
1a810 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
1a820 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1a830 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1a840 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
1a850 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1a860 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1a870 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
1a880 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
1a890 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1a8a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
1a8b0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
1a8c0 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
1a8d0 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
1a8e0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1a8f0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
1a900 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
1a910 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1a920 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1a930 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1a940 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
1a950 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1a960 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1a970 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
1a980 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
1a990 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
1a9a0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
1a9b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1a9c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1a9d0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
1a9e0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
1a9f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
1aa00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1aa10 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
1aa20 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
1aa30 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
1aa40 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
1aa50 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
1aa60 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
1aa70 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
1aa80 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
1aa90 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
1aaa0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
1aab0 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
1aac0 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
1aad0 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
1aae0 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d  llback are zero-
1aaf0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1ab00 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
1ab10 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65  additional.** de
1ab20 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
1ab30 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1ab40 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  horized..**.** ^
1ab50 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1ab60 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
1ab70 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
1ab80 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1ab90 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1aba0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
1abb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1abc0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
1abd0 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
1abe0 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
1abf0 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
1ac00 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
1ac10 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
1ac20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
1ac30 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
1ac40 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
1ac50 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
1ac60 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
1ac70 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
1ac80 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
1ac90 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
1aca0 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
1acb0 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
1acc0 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ble..** ^If the 
1acd0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1ace0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
1acf0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1ad00 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
1ad10 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1ad20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
1ad30 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
1ad40 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
1ad50 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
1ad60 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
1ad70 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
1ad80 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
1ad90 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
1ada0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
1adb0 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
1adc0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1add0 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
1ade0 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
1adf0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
1ae00 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
1ae10 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1ae20 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
1ae30 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
1ae40 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
1ae50 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
1ae60 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
1ae70 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
1ae80 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
1ae90 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
1aea0 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
1aeb0 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
1aec0 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
1aed0 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
1aee0 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
1aef0 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
1af00 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
1af10 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
1af20 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
1af30 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
1af40 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
1af50 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
1af60 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
1af70 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
1af80 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
1af90 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
1afa0 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
1afb0 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
1afc0 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
1afd0 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
1afe0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1aff0 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
1b000 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
1b010 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
1b020 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
1b030 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
1b040 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
1b050 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
1b060 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
1b070 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
1b080 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
1b090 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
1b0a0 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
1b0b0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
1b0c0 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
1b0d0 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
1b0e0 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
1b0f0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
1b100 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
1b110 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
1b120 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
1b130 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
1b140 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
1b150 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
1b160 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1b170 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
1b180 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
1b190 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1b1a0 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
1b1b0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
1b1c0 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
1b1d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
1b1e0 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
1b1f0 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
1b200 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
1b210 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
1b220 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
1b230 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1b240 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
1b250 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
1b260 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
1b270 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b280 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1b290 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
1b2a0 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
1b2b0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1b2c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1b2d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1b2e0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1b2f0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1b300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1b310 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1b320 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1b330 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1b340 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
1b350 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1b360 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
1b370 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
1b380 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
1b390 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
1b3a0 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
1b3b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
1b3c0 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
1b3d0 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
1b3e0 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
1b3f0 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
1b400 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
1b410 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
1b420 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
1b430 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
1b440 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1b450 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
1b460 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
1b470 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1b480 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
1b490 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
1b4a0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1b4b0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
1b4c0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
1b4d0 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
1b4e0 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
1b4f0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
1b500 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1b510 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
1b520 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
1b530 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
1b540 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
1b550 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
1b560 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b570 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
1b580 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
1b590 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
1b5a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1b5b0 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
1b5c0 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
1b5d0 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
1b5e0 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
1b5f0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1b600 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1b610 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
1b620 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
1b630 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
1b640 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1b650 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
1b660 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1b670 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1b680 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1b690 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1b6a0 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
1b6b0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
1b6c0 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
1b6d0 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
1b6e0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
1b6f0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
1b700 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1b710 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
1b720 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
1b730 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
1b740 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1b750 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
1b760 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
1b770 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1b780 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
1b790 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
1b7a0 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
1b7b0 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f   as a [SQLITE_RO
1b7c0 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20  LLBACK | return 
1b7d0 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68  code].** from th
1b7e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
1b7f0 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
1b800 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
1b810 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
1b820 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
1b830 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1b840 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
1b850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b860 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
1b870 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
1b880 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
1b890 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
1b8a0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1b8b0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
1b8c0 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
1b8d0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1b8e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1b8f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
1b900 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
1b910 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
1b920 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
1b930 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
1b940 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1b950 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
1b960 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1b970 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1b980 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
1b990 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
1b9a0 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
1b9b0 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
1b9c0 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
1b9d0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
1b9e0 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
1b9f0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1ba00 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
1ba10 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
1ba20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
1ba30 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
1ba40 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
1ba50 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
1ba60 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
1ba70 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
1ba80 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
1ba90 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
1baa0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1bab0 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
1bac0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
1bad0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
1bae0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
1baf0 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
1bb00 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1bb10 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
1bb20 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1bb30 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1bb40 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1bb50 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1bb60 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
1bb70 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
1bb80 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
1bb90 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
1bba0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1bbb0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
1bbc0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
1bbd0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
1bbe0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
1bbf0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
1bc00 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
1bc10 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
1bc20 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
1bc30 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
1bc40 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
1bc50 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
1bc60 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
1bc70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1bc80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1bc90 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
1bca0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
1bcb0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
1bcc0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
1bcd0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
1bce0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1bcf0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1bd00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1bd10 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
1bd20 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
1bd30 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1bd40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1bd50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1bd60 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1bd70 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
1bd80 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1bd90 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1bda0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1bdb0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1bdc0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
1bdd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1bde0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1bdf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1be00 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1be10 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
1be20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1be30 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1be40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1be50 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
1be60 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
1be70 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1be80 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1be90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1bea0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
1beb0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
1bec0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1bed0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1bee0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bef0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
1bf00 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
1bf10 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1bf20 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1bf30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1bf40 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
1bf50 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
1bf60 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1bf70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1bf80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1bf90 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
1bfa0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
1bfb0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1bfc0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1bfd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1bfe0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
1bff0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
1c000 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1c010 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1c020 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1c030 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1c040 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
1c050 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1c060 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1c070 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1c080 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
1c090 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
1c0a0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1c0b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1c0c0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1c0d0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
1c0e0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
1c0f0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1c100 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1c110 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1c120 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
1c130 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1c140 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c150 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c160 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
1c170 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
1c180 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1c190 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1c1a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c1b0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
1c1c0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
1c1d0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1c1e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1c1f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c200 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
1c210 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
1c220 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1c230 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1c240 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c250 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
1c260 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
1c270 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
1c280 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
1c290 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
1c2a0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
1c2b0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
1c2c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1c2d0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1c2e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c2f0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
1c300 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
1c310 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c320 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c330 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c340 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
1c350 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
1c360 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
1c370 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1c380 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c390 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
1c3a0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
1c3b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1c3c0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1c3d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c3e0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
1c3f0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
1c400 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
1c410 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1c420 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c430 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
1c440 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
1c450 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
1c460 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1c470 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
1c480 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
1c490 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
1c4a0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
1c4b0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1c4c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
1c4d0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
1c4e0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
1c4f0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1c500 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1c510 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
1c520 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
1c530 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
1c540 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1c550 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1c560 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1c570 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
1c580 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
1c590 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1c5a0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1c5b0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1c5c0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
1c5d0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1c5e0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1c5f0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1c600 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
1c610 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
1c620 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1c630 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
1c640 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
1c650 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
1c660 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
1c670 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1c680 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
1c690 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
1c6a0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
1c6b0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
1c6c0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
1c6d0 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
1c6e0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
1c6f0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
1c700 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1c710 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
1c720 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1c730 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
1c740 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
1c750 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
1c760 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
1c770 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
1c780 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1c790 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1c7a0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1c7b0 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
1c7c0 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
1c7d0 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
1c7e0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
1c7f0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
1c800 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
1c810 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
1c820 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1c830 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1c840 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
1c850 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
1c860 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
1c870 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
1c880 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
1c890 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
1c8a0 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
1c8b0 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
1c8c0 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
1c8d0 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
1c8e0 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
1c8f0 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
1c900 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
1c910 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
1c920 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
1c930 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
1c940 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
1c950 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
1c960 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1c970 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1c980 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1c990 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
1c9a0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
1c9b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
1c9c0 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
1c9d0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
1c9e0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
1c9f0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
1ca00 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
1ca10 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
1ca20 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
1ca30 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
1ca40 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
1ca50 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
1ca60 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
1ca70 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
1ca80 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
1ca90 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
1caa0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
1cab0 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
1cac0 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
1cad0 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
1cae0 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
1caf0 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
1cb00 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
1cb10 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
1cb20 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
1cb30 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
1cb40 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
1cb50 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
1cb60 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
1cb70 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
1cb80 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
1cb90 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
1cba0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
1cbb0 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
1cbc0 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
1cbd0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
1cbe0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1cbf0 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
1cc00 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
1cc10 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
1cc20 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
1cc30 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
1cc40 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
1cc50 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58  TE_API SQLITE_EX
1cc60 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
1cc70 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
1cc80 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
1cc90 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
1cca0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
1ccb0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
1ccc0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1ccd0 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
1cce0 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
1ccf0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
1cd00 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1cd10 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
1cd20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
1cd30 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
1cd40 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
1cd50 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
1cd60 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
1cd70 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
1cd80 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1cd90 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
1cda0 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
1cdb0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1cdc0 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
1cdd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
1cde0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
1cdf0 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
1ce00 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
1ce10 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
1ce20 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
1ce30 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
1ce40 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
1ce50 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
1ce60 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
1ce70 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
1ce80 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1ce90 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
1cea0 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e  meter N is the n
1ceb0 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
1cec0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
1ced0 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
1cee0 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
1cef0 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
1cf00 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
1cf10 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
1cf20 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20   X..**.** ^Only 
1cf30 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
1cf40 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
1cf50 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
1cf60 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
1cf70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cf80 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
1cf90 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1cfa0 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
1cfb0 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
1cfc0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
1cfd0 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
1cfe0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1cff0 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
1d000 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1d010 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
1d020 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
1d030 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
1d040 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
1d050 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
1d060 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1d070 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
1d080 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
1d090 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
1d0a0 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
1d0b0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1d0c0 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
1d0d0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
1d0e0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
1d0f0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
1d100 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1d110 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1d120 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1d130 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1d140 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1d150 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1d160 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
1d170 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
1d180 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1d190 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d1a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1d1b0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1d1c0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1d1d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1d1e0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1d1f0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1d200 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1d210 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  **.*/.SQLITE_API
1d220 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72   void sqlite3_pr
1d230 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
1d240 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
1d250 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
1d260 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1d270 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
1d280 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
1d290 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
1d2a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
1d2b0 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
1d2c0 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
1d2d0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
1d2e0 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
1d2f0 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
1d300 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
1d310 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
1d320 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
1d330 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1d340 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1d350 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
1d360 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1d370 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
1d380 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
1d390 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
1d3a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1d3b0 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
1d3c0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
1d3d0 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
1d3e0 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
1d3f0 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
1d400 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
1d410 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
1d420 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1d430 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
1d440 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
1d450 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
1d460 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
1d470 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
1d480 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1d490 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
1d4a0 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
1d4b0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1d4c0 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
1d4d0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
1d4e0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
1d4f0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
1d500 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
1d510 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1d520 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
1d530 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
1d540 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
1d550 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1d560 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
1d570 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
1d580 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
1d590 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
1d5a0 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
1d5b0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
1d5c0 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
1d5d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
1d5e0 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
1d5f0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1d600 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
1d610 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1d620 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
1d630 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1d640 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1d650 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
1d660 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
1d670 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1d680 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
1d690 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
1d6a0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
1d6b0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
1d6c0 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
1d6d0 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
1d6e0 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
1d6f0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
1d700 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1d710 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
1d720 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
1d730 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
1d740 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
1d750 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
1d760 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
1d770 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1d780 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
1d790 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
1d7a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
1d7b0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
1d7c0 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
1d7d0 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
1d7e0 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
1d7f0 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
1d800 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
1d810 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
1d820 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
1d830 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
1d840 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
1d850 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
1d860 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
1d870 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
1d880 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
1d890 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
1d8a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1d8b0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
1d8c0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
1d8d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1d8e0 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
1d8f0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1d900 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
1d910 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
1d920 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
1d930 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
1d940 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1d950 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
1d960 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1d970 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
1d980 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
1d990 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1d9a0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
1d9b0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1d9c0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1d9d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1d9e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1d9f0 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
1da00 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1da10 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1da20 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1da30 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1da40 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
1da50 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
1da60 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
1da70 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
1da80 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
1da90 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
1daa0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
1dab0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
1dac0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
1dad0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1dae0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1daf0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1db00 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
1db10 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1db20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1db30 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1db40 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1db50 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
1db60 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
1db70 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
1db80 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
1db90 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
1dba0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
1dbb0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
1dbc0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1dbd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1dbe0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
1dbf0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
1dc00 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
1dc10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1dc20 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
1dc30 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
1dc40 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
1dc50 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
1dc60 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
1dc70 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
1dc80 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
1dc90 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
1dca0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1dcb0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1dcc0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
1dcd0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1dce0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1dcf0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1dd00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1dd10 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
1dd20 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
1dd30 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
1dd40 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
1dd50 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
1dd60 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
1dd70 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1dd80 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1dd90 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
1dda0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1ddb0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1ddc0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
1ddd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
1dde0 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
1ddf0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1de00 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
1de10 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
1de20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
1de30 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
1de40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1de50 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
1de60 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
1de70 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
1de80 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
1de90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1dea0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
1deb0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
1dec0 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
1ded0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1dee0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
1def0 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
1df00 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
1df10 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
1df20 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
1df30 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1df40 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1df50 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1df60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1df70 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
1df80 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
1df90 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1dfa0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
1dfb0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
1dfc0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
1dfd0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1dfe0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
1dff0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
1e000 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1e010 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
1e020 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
1e030 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
1e040 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
1e050 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1e060 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
1e070 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
1e080 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1e090 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1e0a0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
1e0b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1e0c0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
1e0d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
1e0e0 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
1e0f0 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
1e100 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
1e110 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1e120 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
1e130 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1e140 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
1e150 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
1e160 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
1e170 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1e180 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1e190 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
1e1a0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
1e1b0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
1e1c0 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
1e1d0 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
1e1e0 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
1e1f0 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
1e200 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
1e210 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
1e220 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
1e230 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
1e240 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
1e250 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
1e260 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
1e270 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
1e280 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
1e290 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
1e2a0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
1e2b0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
1e2c0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1e2d0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1e2e0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1e2f0 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
1e300 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
1e310 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
1e320 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
1e330 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1e340 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1e350 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
1e360 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
1e370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1e380 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
1e390 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
1e3a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
1e3b0 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
1e3c0 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
1e3d0 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
1e3e0 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
1e3f0 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
1e400 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
1e410 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
1e420 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
1e430 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
1e440 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1e450 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
1e460 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
1e470 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
1e480 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
1e490 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
1e4a0 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
1e4b0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
1e4c0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
1e4d0 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
1e4e0 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
1e4f0 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
1e500 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
1e510 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
1e520 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
1e530 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
1e540 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
1e550 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
1e560 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
1e570 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73  me option..** As
1e580 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
1e590 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69  on 3.7.7, URI fi
1e5a0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
1e5b0 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
1e5c0 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
1e5d0 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
1e5e0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
1e5f0 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
1e600 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
1e610 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
1e620 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
1e630 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
1e640 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1e650 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1e660 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
1e670 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
1e680 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
1e690 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
1e6a0 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
1e6b0 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
1e6c0 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
1e6d0 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
1e6e0 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
1e6f0 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
1e700 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
1e710 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
1e720 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
1e730 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
1e740 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1e750 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
1e760 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
1e770 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
1e780 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
1e790 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
1e7a0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
1e7b0 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
1e7c0 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
1e7d0 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
1e7e0 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
1e7f0 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
1e800 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
1e810 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
1e820 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
1e830 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
1e840 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
1e850 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
1e860 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
1e870 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
1e880 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
1e890 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
1e8a0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
1e8b0 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
1e8c0 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
1e8d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
1e8e0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1e8f0 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
1e900 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64  th. .** ^On wind
1e910 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
1e920 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
1e930 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
1e940 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
1e950 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
1e960 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  "C:")..**.** [[c
1e970 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
1e980 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
1e990 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
1e9a0 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
1e9b0 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
1e9c0 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
1e9d0 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
1e9e0 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
1e9f0 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
1ea00 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
1ea10 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
1ea20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65   SQLite interpre
1ea30 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ts the following
1ea40 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72   three query par
1ea50 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
1ea60 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
1ea70 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
1ea80 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
1ea90 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
1eaa0 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
1eab0 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
1eac0 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
1ead0 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
1eae0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1eaf0 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
1eb00 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
1eb10 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1eb20 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
1eb30 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
1eb40 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
1eb50 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
1eb60 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
1eb70 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
1eb80 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
1eb90 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
1eba0 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
1ebb0 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
1ebc0 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
1ebd0 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
1ebe0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
1ebf0 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
1ec00 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
1ec10 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
1ec20 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
1ec30 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
1ec40 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
1ec50 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1ec60 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1ec70 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
1ec80 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
1ec90 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
1eca0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
1ecb0 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
1ecc0 2c 20 22 72 77 22 20 6f 72 0a 2a 2a 20 20 20 20  , "rw" or.**    
1ecd0 20 22 72 77 63 22 2e 20 41 74 74 65 6d 70 74 69   "rwc". Attempti
1ece0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
1ecf0 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
1ed00 69 73 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a  is an error)^. .
1ed10 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
1ed20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
1ed30 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1ed40 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1ed50 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
1ed60 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
1ed70 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
1ed80 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
1ed90 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
1eda0 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
1edb0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
1edc0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1edd0 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
1ede0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
1edf0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
1ee00 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
1ee10 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1ee20 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
1ee30 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
1ee40 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
1ee50 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
1ee60 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
1ee70 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
1ee80 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
1ee90 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
1eea0 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
1eeb0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
1eec0 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
1eed0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
1eee0 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
1eef0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 5e  E_OPEN_CREATE. ^
1ef00 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
1ef10 76 32 28 29 20 69 73 20 0a 2a 2a 20 20 20 20 20  v2() is .**     
1ef20 75 73 65 64 2c 20 69 74 20 69 73 20 61 6e 20 65  used, it is an e
1ef30 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
1ef40 61 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  a value for the 
1ef50 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
1ef60 68 61 74 20 69 73 20 0a 2a 2a 20 20 20 20 20 6c  hat is .**     l
1ef70 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
1ef80 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
1ef90 69 65 64 20 62 79 20 74 68 65 20 66 6c 61 67 73  ied by the flags
1efa0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
1efb0 68 69 72 64 20 0a 2a 2a 20 20 20 20 20 70 61 72  hird .**     par
1efc0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 20 20  ameter..**.**   
1efd0 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
1efe0 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
1eff0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
1f000 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
1f010 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
1f020 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
1f030 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
1f040 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
1f050 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
1f060 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
1f070 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
1f080 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
1f090 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
1f0a0 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
1f0b0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
1f0c0 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
1f0d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
1f0e0 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
1f0f0 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
1f100 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
1f110 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1f120 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
1f130 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
1f140 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
1f150 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
1f160 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
1f170 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
1f180 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
1f190 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
1f1a0 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20  s any behaviour 
1f1b0 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
1f1c0 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
1f1d0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1f1e0 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
1f1f0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
1f200 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  flag..** </ul>.*
1f210 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
1f220 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
1f230 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
1f240 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
1f250 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
1f260 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
1f270 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1f280 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
1f290 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
1f2a0 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
1f2b0 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
1f2c0 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
1f2d0 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
1f2e0 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
1f2f0 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
1f300 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1f310 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
1f320 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
1f330 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
1f340 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
1f350 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
1f360 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
1f370 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
1f380 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
1f390 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
1f3a0 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
1f3b0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
1f3c0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
1f3d0 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
1f3e0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
1f3f0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
1f400 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
1f410 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
1f420 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
1f430 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
1f440 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
1f450 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
1f460 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
1f470 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
1f480 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
1f490 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
1f4a0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
1f4b0 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
1f4c0 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
1f4d0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
1f4e0 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
1f4f0 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
1f500 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
1f510 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
1f520 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
1f530 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
1f540 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
1f550 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
1f560 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
1f570 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
1f580 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
1f590 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
1f5a0 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
1f5b0 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
1f5c0 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
1f5d0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
1f5e0 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
1f5f0 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
1f600 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
1f610 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
1f620 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
1f630 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
1f640 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
1f650 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
1f660 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
1f670 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
1f680 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
1f690 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
1f6a0 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
1f6b0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
1f6c0 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
1f6d0 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
1f6e0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
1f6f0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
1f700 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
1f710 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
1f720 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
1f730 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
1f740 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1f750 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
1f760 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
1f770 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
1f780 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
1f790 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
1f7a0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
1f7b0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
1f7c0 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20  vfs=unix-nolock 
1f7d0 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
1f7e0 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
1f7f0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
1f800 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
1f810 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63   VFS "unix-noloc
1f820 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  k"..** <tr><td> 
1f830 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
1f840 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
1f850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
1f860 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
1f870 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
1f880 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
1f890 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
1f8a0 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
1f8b0 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
1f8c0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
1f8d0 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
1f8e0 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
1f8f0 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
1f900 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
1f910 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
1f920 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
1f930 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
1f940 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
1f950 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
1f960 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
1f970 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
1f980 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
1f990 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
1f9a0 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
1f9b0 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
1f9c0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
1f9d0 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
1f9e0 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
1f9f0 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
1fa00 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
1fa10 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
1fa20 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
1fa30 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
1fa40 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
1fa50 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
1fa60 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
1fa70 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
1fa80 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
1fa90 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
1faa0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
1fab0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
1fac0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
1fad0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
1fae0 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
1faf0 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
1fb00 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
1fb10 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
1fb20 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
1fb30 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1fb40 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
1fb50 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
1fb60 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
1fb70 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
1fb80 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
1fb90 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
1fba0 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
1fbb0 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
1fbc0 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
1fbd0 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
1fbe0 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
1fbf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1fc00 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1fc10 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 53 51 4c 49  en_v2()..*/.SQLI
1fc20 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1fc30 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
1fc40 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
1fc50 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1fc60 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
1fc70 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1fc80 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
1fc90 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1fca0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49  andle */.);.SQLI
1fcb0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1fcc0 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
1fcd0 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
1fce0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1fcf0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
1fd00 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
1fd10 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1fd20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1fd30 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53  b handle */.);.S
1fd40 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1fd50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
1fd60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
1fd70 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1fd80 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1fd90 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
1fda0 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
1fdb0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1fdc0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
1fdd0 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
1fde0 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
1fdf0 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
1fe00 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
1fe10 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
1fe20 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
1fe30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fe40 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
1fe50 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
1fe60 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ers.**.** These 
1fe70 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74  are utility rout
1fe80 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20  ines, useful to 
1fe90 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
1fea0 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a  ons, that check.
1feb0 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
1fec0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
1fed0 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
1fee0 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
1fef0 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
1ff00 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
1ff10 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
1ff20 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20  e of that query 
1ff30 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1ff40 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74   If F is the dat
1ff50 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70  abase filename p
1ff60 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
1ff70 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d  to the xOpen() m
1ff80 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56  ethod of .** a V
1ff90 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1ffa0 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73  n when the flags
1ffb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
1ffc0 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72  pen() has one or
1ffd0 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65   .** more of the
1ffe0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
1fff0 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  I] or [SQLITE_OP
20000 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73  EN_MAIN_DB] bits
20010 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73   set and.** P is
20020 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
20030 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
20040 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
20050 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
20060 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65  F,P) returns the
20070 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a   value of the P.
20080 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
20090 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e  it exists or a N
200a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50  ULL pointer if P
200b0 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72   does not appear
200c0 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20   as a .** query 
200d0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20  parameter on F. 
200e0 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79   If P is a query
200f0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a   parameter of F.
20100 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63  ** has no explic
20110 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73  it value, then s
20120 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
20130 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
20140 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
20150 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
20160 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  g..**.** The sql
20170 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
20180 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
20190 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69  assumes that P i
201a0 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70  s a boolean.** p
201b0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
201c0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72  urns true (1) or
201d0 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72   false (0) accor
201e0 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75  ding to the valu
201f0 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20  e.** of P.  The 
20200 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 74 72  value of P is tr
20210 75 65 20 69 66 20 69 74 20 69 73 20 22 79 65 73  ue if it is "yes
20220 22 20 6f 72 20 22 74 72 75 65 22 20 6f 72 20 22  " or "true" or "
20230 6f 6e 22 20 6f 72 20 0a 2a 2a 20 61 20 6e 6f 6e  on" or .** a non
20240 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 20 61 6e 64  -zero number and
20250 20 69 73 20 66 61 6c 73 65 20 6f 74 68 65 72 77   is false otherw
20260 69 73 65 2e 20 20 49 66 20 50 20 69 73 20 6e 6f  ise.  If P is no
20270 74 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65  t a query parame
20280 74 65 72 0a 2a 2a 20 6f 6e 20 46 20 74 68 65 6e  ter.** on F then
20290 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
202a0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
202b0 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a  rns (B!=0)..**.*
202c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
202d0 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72  i_int64(F,P,D) r
202e0 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20  outine converts 
202f0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
20300 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20  nto a.** 64-bit 
20310 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
20320 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  nd returns that 
20330 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66  integer, or D if
20340 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65   P does not.** e
20350 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61  xist.  If the va
20360 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65  lue of P is some
20370 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
20380 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
20390 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74  n.** zero is ret
203a0 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  urned..** .** If
203b0 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   F is a NULL poi
203c0 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  nter, then sqlit
203d0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
203e0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55  (F,P) returns NU
203f0 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  LL and.** sqlite
20400 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
20410 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20  P,B) returns B. 
20420 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e   If F is not a N
20430 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a  ULL pointer and.
20440 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  ** is not a data
20450 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61  base file pathna
20460 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  me pointer that 
20470 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e  SQLite passed in
20480 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
20490 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  VFS method, then
204a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
204b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
204c0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
204d0 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73  robably.** undes
204e0 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54  irable..*/.SQLIT
204f0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
20500 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
20510 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
20520 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
20530 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
20540 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  m);.SQLITE_API i
20550 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
20560 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
20570 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
20580 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
20590 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c  t bDefault);.SQL
205a0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
205b0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
205c0 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
205d0 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
205e0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
205f0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
20600 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
20610 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
20620 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20630 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
20640 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
20650 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
20660 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
20670 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
20680 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
20690 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
206a0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
206b0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
206c0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
206d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
206e0 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
206f0 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
20700 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
20710 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
20720 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
20730 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
20740 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
20750 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
20760 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
20770 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
20780 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
20790 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
207a0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
207b0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
207c0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
207d0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
207e0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
207f0 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
20800 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
20810 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
20820 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
20830 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
20840 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
20850 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
20860 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
20870 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
20880 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
20890 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
208a0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
208b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
208c0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
208d0 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
208e0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
208f0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
20900 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
20910 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
20920 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
20930 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
20940 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
20950 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
20960 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
20970 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
20980 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
20990 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
209a0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
209b0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
209c0 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
209d0 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
209e0 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
209f0 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
20a00 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
20a10 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
20a20 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
20a30 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
20a40 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
20a50 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
20a60 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
20a70 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
20a80 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
20a90 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
20aa0 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
20ab0 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
20ac0 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
20ad0 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
20ae0 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
20af0 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
20b00 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
20b10 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
20b20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
20b30 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
20b40 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
20b50 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
20b60 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
20b70 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
20b80 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
20b90 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
20ba0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
20bb0 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
20bc0 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
20bd0 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
20be0 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
20bf0 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
20c00 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
20c10 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
20c20 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
20c30 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
20c40 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
20c50 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
20c60 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
20c70 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
20c80 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
20c90 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
20ca0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
20cb0 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
20cc0 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54  be set..*/.SQLIT
20cd0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
20ce0 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
20cf0 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41  3 *db);.SQLITE_A
20d00 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
20d10 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
20d20 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51  sqlite3 *db);.SQ
20d30 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
20d40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
20d50 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53  msg(sqlite3*);.S
20d60 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
20d70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
20d80 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
20d90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20da0 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
20db0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
20dc0 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
20dd0 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
20de0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
20df0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
20e00 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
20e10 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
20e20 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
20e30 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
20e40 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
20e50 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
20e60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
20e70 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
20e80 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
20e90 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
20ea0 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
20eb0 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
20ec0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
20ed0 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
20ee0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
20ef0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
20f00 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
20f10 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
20f20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
20f30 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
20f40 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
20f50 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
20f60 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
20f70 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
20f80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
20f90 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
20fa0 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
20fb0 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
20fc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
20fd0 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
20fe0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
20ff0 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
21000 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
21010 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
21020 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
21030 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
21040 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
21050 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
21060 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
21070 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
21080 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
21090 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
210a0 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
210b0 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
210c0 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
210d0 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
210e0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
210f0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
21100 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
21110 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
21120 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
21130 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
21140 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
21150 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
21160 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
21170 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
21180 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
21190 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
211a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
211b0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
211c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
211d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
211e0 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
211f0 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
21200 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
21210 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
21220 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
21230 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
21240 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
21250 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
21260 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
21270 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
21280 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
21290 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
212a0 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
212b0 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
212c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
212d0 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
212e0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
212f0 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
21300 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
21310 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
21320 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
21330 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
21340 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
21350 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
21360 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
21370 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
21380 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
21390 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
213a0 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
213b0 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
213c0 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
213d0 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
213e0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
213f0 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
21400 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
21410 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
21420 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
21430 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
21440 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
21450 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
21460 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
21470 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
21480 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
21490 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
214a0 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
214b0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
214c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
214d0 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
214e0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
214f0 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
21500 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
21510 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
21520 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
21530 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
21540 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
21550 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
21560 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
21570 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
21580 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
21590 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
215a0 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
215b0 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
215c0 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
215d0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
215e0 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
215f0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
21600 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
21610 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
21620 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
21630 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
21640 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
21650 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
21660 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
21670 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
21680 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
21690 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
216a0 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
216b0 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
216c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
216d0 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
216e0 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
216f0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
21700 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
21710 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
21720 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
21730 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
21740 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
21750 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
21760 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
21770 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
21780 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
21790 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
217a0 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
217b0 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
217c0 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
217d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
217e0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
217f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
21800 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
21810 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
21820 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
21830 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
21840 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
21850 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
21860 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
21870 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
21880 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
21890 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
218a0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
218b0 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
218c0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
218d0 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49  eleases..*/.SQLI
218e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
218f0 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
21900 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
21910 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
21920 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
21930 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
21940 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
21950 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
21960 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
21970 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
21980 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
21990 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
219a0 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
219b0 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
219c0 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
219d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
219e0 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
219f0 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
21a00 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
21a10 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
21a20 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
21a30 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
21a40 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
21a50 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
21a60 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
21a70 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
21a80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
21a90 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
21aa0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
21ab0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
21ac0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
21ad0 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
21ae0 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
21af0 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
21b00 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
21b10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
21b20 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
21b30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
21b40 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
21b50 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
21b60 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
21b70 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
21b80 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
21b90 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
21ba0 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
21bb0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
21bc0 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
21bd0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
21be0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
21bf0 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
21c00 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
21c10 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
21c20 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
21c30 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
21c40 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
21c50 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
21c60 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
21c70 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
21c80 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
21c90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
21ca0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
21cb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
21cc0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
21cd0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
21ce0 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
21cf0 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
21d00 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
21d10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
21d20 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
21d30 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
21d40 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
21d50 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
21d60 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
21d70 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
21d80 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
21d90 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
21da0 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
21db0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
21dc0 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
21dd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
21de0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
21df0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
21e00 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
21e10 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
21e20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
21e30 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
21e40 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
21e50 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
21e60 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
21e70 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
21e80 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
21e90 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
21ea0 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
21eb0 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
21ec0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
21ed0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
21ee0 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
21ef0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
21f00 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
21f10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
21f20 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
21f30 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
21f40 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
21f50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
21f60 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
21f70 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
21f80 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
21f90 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
21fa0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
21fb0 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
21fc0 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
21fd0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
21fe0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
21ff0 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
22000 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
22010 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
22020 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
22030 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
22040 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
22050 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
22060 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
22070 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
22080 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
22090 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
220a0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
220b0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
220c0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
220d0 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
220e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
220f0 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
22100 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
22110 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
22120 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
22130 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
22140 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
22150 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
22160 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
22170 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
22180 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
22190 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
221a0 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  gers.</dd>)^.** 
221b0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
221c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
221d0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
221e0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
221f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
22200 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
22210 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
22220 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
22230 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
22240 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
22250 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
22260 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
22270 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
22280 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
22290 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
222a0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
222b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
222c0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
222d0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
222e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
222f0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
22300 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
22310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
22320 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
22330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
22340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22350 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
22360 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
22370 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
22380 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
22390 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
223a0 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
223b0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
223c0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
223d0 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   10../*.** CAPI3
223e0 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
223f0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
22400 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
22410 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
22420 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
22430 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
22440 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
22450 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
22460 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
22470 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
22480 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
22490 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
224a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
224b0 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
224c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
224d0 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
224e0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
224f0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
22500 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
22510 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
22520 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
22530 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
22540 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
22550 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
22560 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
22570 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
22580 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
22590 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
225a0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
225b0 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
225c0 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
225d0 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
225e0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
225f0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
22600 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
22610 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
22620 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
22630 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
22640 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
22650 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
22660 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
22670 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
22680 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
22690 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
226a0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
226b0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
226c0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
226d0 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
226e0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
226f0 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
22700 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
22710 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
22720 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65  ql.  ^When nByte
22730 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
22740 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
22750 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
22760 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
22770 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
22780 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
22790 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
227a0 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
227b0 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
227c0 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
227d0 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
227e0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
227f0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
22800 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
22810 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
22820 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
22830 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
22840 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
22850 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
22860 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
22870 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
22880 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
22890 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
228a0 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
228b0 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
228c0 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53   as this saves S
228d0 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e  QLite from havin
228e0 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63  g to.** make a c
228f0 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74  opy of the input
22900 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
22910 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
22920 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
22930 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
22940 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
22950 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
22960 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
22970 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
22980 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
22990 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
229a0 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
229b0 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
229c0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
229d0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
229e0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
229f0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
22a00 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
22a10 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
22a20 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
22a30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22a40 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
22a50 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
22a60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
22a70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
22a80 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
22a90 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
22aa0 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
22ab0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
22ac0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
22ad0 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
22ae0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
22af0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
22b00 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
22b10 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
22b20 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
22b30 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
22b40 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
22b50 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
22b60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
22b70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
22b80 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
22b90 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
22ba0 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
22bb0 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
22bc0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
22bd0 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
22be0 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
22bf0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
22c00 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
22c10 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
22c20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
22c30 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
22c40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
22c50 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
22c60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
22c70 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
22c80 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
22c90 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
22ca0 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
22cb0 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
22cc0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
22cd0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
22ce0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
22cf0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
22d00 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
22d10 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
22d20 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
22d30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22d40 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
22d50 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
22d60 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
22d70 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
22d80 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
22d90 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
22da0 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
22db0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
22dc0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
22dd0 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
22de0 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
22df0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
22e00 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
22e10 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
22e20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
22e30 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
22e40 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
22e50 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
22e60 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
22e70 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
22e80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
22e90 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
22ea0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
22eb0 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
22ec0 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  gain..** </li>.*
22ed0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
22ee0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
22ef0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
22f00 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
22f10 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
22f20 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
22f30 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
22f40 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
22f50 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
22f60 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
22f70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
22f80 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
22f90 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
22fa0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
22fb0 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
22fc0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
22fd0 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
22fe0 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
22ff0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
23000 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
23010 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
23020 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
23030 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
23040 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
23050 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
23060 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
23070 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
23080 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
23090 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
230a0 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
230b0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
230c0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
230d0 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
230e0 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
230f0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
23100 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
23110 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
23120 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
23130 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
23140 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
23150 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
23160 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
23170 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
23180 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
23190 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
231a0 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
231b0 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
231c0 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
231d0 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
231e0 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
231f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
23200 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
23210 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
23220 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
23230 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
23240 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
23250 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
23260 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
23270 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
23280 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
23290 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
232a0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
232b0 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
232c0 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
232d0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
232e0 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
232f0 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
23300 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
23310 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
23320 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
23330 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
23340 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c  ..** the .** </l
23350 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53  i>.** </ol>.*/.S
23360 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
23370 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
23380 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
23390 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
233a0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
233b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
233c0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
233d0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
233e0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
233f0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
23400 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
23410 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
23420 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
23430 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
23440 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
23450 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
23460 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
23470 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
23480 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
23490 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
234a0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
234b0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
234c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
234d0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
234e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
234f0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
23500 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
23510 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
23520 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
23530 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
23540 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
23550 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
23560 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
23570 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
23580 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
23590 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
235a0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
235b0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
235c0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
235d0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
235e0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
235f0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
23600 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
23610 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
23620 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
23630 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
23640 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
23650 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
23660 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
23670 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
23680 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
23690 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
236a0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
236b0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
236c0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
236d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
236e0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
236f0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
23700 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
23710 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
23720 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
23730 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
23740 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
23750 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
23760 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
23770 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
23780 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
23790 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
237a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
237b0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
237c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
237d0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
237e0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
237f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
23800 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
23810 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
23820 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
23830 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
23840 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
23850 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
23860 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
23870 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
23880 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
23890 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
238a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
238b0 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
238c0 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a  tatement SQL.**.
238d0 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
238e0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
238f0 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
23900 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
23910 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
23920 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
23930 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
23940 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
23950 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
23960 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
23970 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
23980 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
23990 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
239a0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  are16_v2()]..*/.
239b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
239c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
239d0 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
239e0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
239f0 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
23a00 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
23a10 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54  atement Writes T
23a20 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a  he Database.**.*
23a30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
23a40 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
23a50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
23a60 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
23a70 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
23a80 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
23a90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
23aa0 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
23ab0 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
23ac0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
23ad0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
23ae0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
23af0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
23b00 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
23b10 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
23b20 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
23b30 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
23b40 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
23b50 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
23b60 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
23b70 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
23b80 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
23b90 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
23ba0 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
23bb0 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
23bc0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
23bd0 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
23be0 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
23bf0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
23c00 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
23c10 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
23c20 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
23c30 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
23c40 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
23c50 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
23c60 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
23c70 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
23c80 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
23c90 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
23ca0 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
23cb0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
23cc0 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
23cd0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
23ce0 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
23cf0 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
23d00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
23d10 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
23d20 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
23d30 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
23d40 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
23d50 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
23d60 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
23d70 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
23d80 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
23d90 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
23da0 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
23db0 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
23dc0 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
23dd0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
23de0 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
23df0 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
23e00 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
23e10 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
23e20 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
23e30 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
23e40 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
23e50 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
23e60 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
23e70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
23e80 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
23e90 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
23ea0 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
23eb0 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
23ec0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
23ed0 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
23ee0 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
23ef0 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
23f00 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
23f10 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
23f20 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
23f30 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45   disk..*/.SQLITE
23f40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
23f50 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73  _stmt_readonly(s
23f60 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
23f70 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
23f80 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
23f90 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  If A Prepared St
23fa0 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e  atement Has Been
23fb0 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68   Reset.**.** ^Th
23fc0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
23fd0 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65  usy(S) interface
23fe0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
23ff0 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a  on-zero) if the.
24000 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
24010 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65  tement] S has be
24020 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65  en stepped at le
24030 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a  ast once using .
24040 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
24050 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74  (S)] but has not
24060 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
24070 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f  on and/or has no
24080 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74  t .** been reset
24090 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
240a0 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65  reset(S)].  ^The
240b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
240c0 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61  sy(S).** interfa
240d0 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  ce returns false
240e0 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20   if S is a NULL 
240f0 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69  pointer.  If S i
24100 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c  s not a .** NULL
24110 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20   pointer and is 
24120 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  not a pointer to
24130 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72   a valid [prepar
24140 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
24150 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68   object, then th
24160 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
24170 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
24180 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
24190 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
241a0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
241b0 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f  ed in combinatio
241c0 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
241d0 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f  stmt()].** to lo
241e0 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65  cate all prepare
241f0 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
24200 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64  ociated with a d
24210 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e  atabase .** conn
24220 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20  ection that are 
24230 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67  in need of being
24240 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61   reset.  This ca
24250 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f  n be used,.** fo
24260 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69  r example, in di
24270 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65  agnostic routine
24280 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20  s to search for 
24290 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61  prepared .** sta
242a0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  tements that are
242b0 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73   holding a trans
242c0 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a  action open..*/.
242d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
242e0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
242f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
24300 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24310 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
24320 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
24330 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
24340 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
24350 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
24360 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
24370 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
24380 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
24390 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
243a0 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
243b0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
243c0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
243d0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
243e0 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
243f0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
24400 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
24410 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
24420 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
24430 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
24440 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
24450 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
24460 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
24470 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
24480 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
24490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
244a0 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
244b0 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
244c0 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
244d0 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
244e0 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
244f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
24500 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
24510 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
24520 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
24530 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
24540 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
24550 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
24560 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
24570 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
24580 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
24590 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
245a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
245b0 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
245c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
245d0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
245e0 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
245f0 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
24600 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
24610 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
24620 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
24630 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
24640 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
24650 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
24660 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
24670 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
24680 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
24690 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
246a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
246b0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
246c0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
246d0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
246e0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
246f0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
24700 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
24710 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
24720 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
24730 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
24740 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
24750 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
24760 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
24770 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
24780 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
24790 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
247a0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
247b0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
247c0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
247d0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
247e0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
247f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
24800 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
24810 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
24820 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
24830 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
24840 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
24850 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
24860 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
24870 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
24880 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
24890 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
248a0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
248b0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
248c0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
248d0 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
248e0 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
248f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
24900 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
24910 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
24920 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
24930 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
24940 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
24950 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
24960 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
24970 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
24980 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
24990 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
249a0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
249b0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
249c0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
249d0 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
249e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
249f0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
24a00 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
24a10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
24a20 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
24a30 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
24a40 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
24a50 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
24a60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
24a70 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
24a80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
24a90 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
24aa0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
24ab0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
24ac0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
24ad0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
24ae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
24af0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
24b00 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
24b10 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
24b20 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
24b30 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
24b40 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
24b50 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
24b60 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
24b70 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
24b80 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
24b90 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
24ba0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
24bb0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
24bc0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
24bd0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
24be0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
24bf0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
24c00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
24c10 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
24c20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
24c30 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
24c40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
24c50 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
24c60 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
24c70 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
24c80 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
24c90 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
24ca0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
24cb0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
24cc0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
24cd0 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
24ce0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
24cf0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
24d00 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24d10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
24d20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
24d30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24d40 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
24d50 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
24d60 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
24d70 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
24d80 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
24d90 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
24da0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
24db0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
24dc0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
24dd0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
24de0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
24df0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
24e00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
24e10 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
24e20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
24e30 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
24e40 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
24e50 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
24e60 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
24e70 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
24e80 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
24e90 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
24ea0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
24eb0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
24ec0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
24ed0 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
24ee0 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
24ef0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
24f00 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
24f10 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
24f20 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
24f30 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
24f40 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
24f50 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
24f60 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
24f70 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
24f80 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
24f90 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
24fa0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
24fb0 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
24fc0 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
24fd0 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
24fe0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
24ff0 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
25000 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
25010 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
25020 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
25030 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
25040 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
25050 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
25060 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
25070 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
25080 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
25090 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
250a0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
250b0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
250c0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
250d0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
250e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
250f0 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
25100 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
25110 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
25120 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
25130 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
25140 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
25150 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
25160 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
25170 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
25180 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
25190 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
251a0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
251b0 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
251c0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
251d0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
251e0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
251f0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
25200 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
25210 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
25220 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
25230 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
25240 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
25250 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
25260 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
25270 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
25280 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
25290 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
252a0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
252b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
252c0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
252d0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
252e0 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
252f0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
25300 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
25310 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
25320 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  eter..**.** ^(In
25330 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
25340 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
25350 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
25360 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
25370 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
25380 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
25390 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
253a0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
253b0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
253c0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
253d0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
253e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
253f0 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
25400 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
25410 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
25420 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  e, the length of
25430 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
25440 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
25450 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
25460 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
25470 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e  nator..** If a n
25480 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
25490 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
254a0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
254b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
254c0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
254d0 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e  nd_text16() then
254e0 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
254f0 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
25500 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
25510 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
25520 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
25530 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
25540 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
25550 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
25560 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
25570 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
25580 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
25590 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
255a0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
255b0 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
255c0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
255d0 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
255e0 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
255f0 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
25600 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
25610 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
25620 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
25630 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
25640 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
25650 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
25660 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
25670 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
25680 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
25690 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
256a0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
256b0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
256c0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
256d0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
256e0 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
256f0 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
25700 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
25710 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
25720 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
25730 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
25740 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
25750 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  the call to sqli
25760 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
25770 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
25780 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69  _text(), or sqli
25790 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
257a0 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49  ) fails.  .** ^I
257b0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
257c0 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
257d0 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
257e0 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
257f0 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
25800 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
25810 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
25820 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
25830 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
25840 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
25850 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
25860 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
25870 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
25880 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
25890 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
258a0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
258b0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
258c0 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
258d0 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
258e0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
258f0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
25900 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
25910 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
25920 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
25930 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
25940 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
25950 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
25960 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
25970 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
25980 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
25990 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
259a0 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
259b0 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
259c0 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
259d0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
259e0 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
259f0 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
25a00 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
25a10 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
25a20 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
25a30 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
25a40 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
25a50 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
25a60 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
25a70 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
25a80 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
25a90 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
25aa0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
25ab0 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
25ac0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
25ad0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
25ae0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
25af0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
25b00 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
25b10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25b20 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
25b30 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25b40 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
25b50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25b60 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
25b70 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
25b80 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
25b90 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
25ba0 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
25bb0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
25bc0 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
25bd0 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
25be0 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
25bf0 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
25c00 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
25c10 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
25c20 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
25c30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
25c40 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
25c50 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
25c60 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
25c70 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
25c80 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
25c90 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
25ca0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
25cb0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
25cc0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
25cd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
25ce0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
25cf0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
25d00 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
25d10 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
25d20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
25d30 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
25d40 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
25d50 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
25d60 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
25d70 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
25d80 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
25d90 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
25da0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
25db0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
25dc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
25dd0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
25de0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
25df0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
25e00 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
25e10 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
25e20 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
25e30 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
25e40 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
25e50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25e60 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
25e70 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
25e80 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
25e90 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
25ea0 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
25eb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
25ec0 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41  ouble);.SQLITE_A
25ed0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
25ee0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
25ef0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
25f00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
25f10 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
25f20 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
25f30 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
25f40 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41  int64);.SQLITE_A
25f50 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
25f60 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
25f70 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  _stmt*, int);.SQ
25f80 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
25f90 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
25fa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25fb0 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
25fc0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
25fd0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
25fe0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
25ff0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
26000 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
26010 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
26020 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
26030 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
26040 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
26050 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
26060 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
26070 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
26080 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
26090 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
260a0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
260b0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
260c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
260d0 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
260e0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
260f0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
26100 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
26110 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
26120 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
26130 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
26140 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
26150 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
26160 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
26170 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
26180 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
26190 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
261a0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
261b0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
261c0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
261d0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
261e0 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
261f0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
26200 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
26210 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
26220 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
26230 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
26240 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
26250 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
26260 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
26270 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
26280 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
26290 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
262a0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
262b0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
262c0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
262d0 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
262e0 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
262f0 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
26300 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
26310 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
26320 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
26330 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
26340 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
26350 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
26360 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
26370 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26380 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
26390 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
263a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
263b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
263c0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
263d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
263e0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
263f0 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a  t Parameter.**.*
26400 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
26410 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
26420 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
26430 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
26440 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
26450 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
26460 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
26470 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
26480 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
26490 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
264a0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
264b0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
264c0 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
264d0 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
264e0 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
264f0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
26500 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
26510 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
26520 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
26530 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
26540 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
26550 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
26560 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
26570 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
26580 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
26590 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
265a0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
265b0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
265c0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
265d0 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
265e0 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
265f0 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
26600 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
26610 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
26620 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
26630 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
26640 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
26650 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
26660 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
26670 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
26680 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
26690 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
266a0 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
266b0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
266c0 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
266d0 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
266e0 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
266f0 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
26700 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
26710 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
26720 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26730 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
26740 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
26750 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
26760 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
26770 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
26780 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
26790 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
267a0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
267b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
267c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
267d0 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
267e0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
267f0 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
26800 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
26810 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
26820 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26830 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
26840 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
26850 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20  iven Name.**.** 
26860 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
26870 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
26880 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
26890 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
268a0 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
268b0 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
268c0 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
268d0 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
268e0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
268f0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
26900 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
26910 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
26920 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
26930 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
26940 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
26950 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
26960 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
26970 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
26980 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
26990 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
269a0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
269b0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
269c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
269d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
269e0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
269f0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
26a00 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
26a10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
26a20 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
26a30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
26a40 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
26a50 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
26a60 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
26a70 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
26a80 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
26a90 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
26aa0 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
26ab0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
26ac0 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
26ad0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
26ae0 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  ent.**.** ^Contr
26af0 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
26b00 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
26b10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
26b20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
26b30 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
26b40 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
26b50 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
26b60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
26b70 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
26b80 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
26b90 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
26ba0 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51  s to NULL..*/.SQ
26bb0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
26bc0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
26bd0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
26be0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
26bf0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
26c00 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
26c10 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  lt Set.**.** ^Re
26c20 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
26c30 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
26c40 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
26c50 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
26c60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26c70 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
26c80 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
26c90 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
26ca0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
26cb0 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
26cc0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
26cd0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
26ce0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
26cf0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
26d00 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c  _count()].*/.SQL
26d10 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
26d20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
26d30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
26d40 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
26d50 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
26d60 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
26d70 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73   Set.**.** ^Thes
26d80 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
26d90 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
26da0 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
26db0 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
26dc0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
26dd0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
26de0 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
26df0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
26e00 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
26e10 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
26e20 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
26e30 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
26e40 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
26e50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26e60 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
26e70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
26e80 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
26e90 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
26ea0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
26eb0 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
26ec0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
26ed0 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
26ee0 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
26ef0 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
26f00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
26f10 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
26f20 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
26f30 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
26f40 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
26f50 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
26f60 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
26f70 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
26f80 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
26f90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
26fa0 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
26fb0 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
26fc0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
26fd0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
26fe0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
26ff0 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
27000 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
27010 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
27020 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
27030 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
27040 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
27050 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
27060 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
27070 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27080 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
27090 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
270a0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
270b0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
270c0 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
270d0 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
270e0 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
270f0 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
27100 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
27110 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
27120 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
27130 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
27140 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
27150 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
27160 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
27170 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
27180 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
27190 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
271a0 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
271b0 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
271c0 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
271d0 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
271e0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
271f0 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
27200 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
27210 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
27220 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
27230 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45   next..*/.SQLITE
27240 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
27250 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
27260 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
27270 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49  t*, int N);.SQLI
27280 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
27290 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
272a0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
272b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
272c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
272d0 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
272e0 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
272f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
27300 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
27310 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
27320 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
27330 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
27340 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
27350 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
27360 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
27370 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
27380 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
27390 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
273a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
273b0 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
273c0 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
273d0 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
273e0 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
273f0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
27400 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
27410 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
27420 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
27430 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
27440 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
27450 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
27460 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
27470 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
27480 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
27490 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
274a0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
274b0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
274c0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
274d0 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
274e0 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
274f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
27500 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
27510 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
27520 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
27530 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
27540 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
27550 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
27560 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
27570 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
27580 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
27590 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
275a0 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
275b0 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
275c0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
275d0 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
275e0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
275f0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
27600 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
27610 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
27620 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
27630 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
27640 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
27650 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
27660 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
27670 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
27680 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
27690 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
276a0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
276b0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
276c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
276d0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
276e0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
276f0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
27700 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
27710 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
27720 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
27730 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
27740 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
27750 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
27760 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
27770 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
27780 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
27790 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
277a0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
277b0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
277c0 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
277d0 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
277e0 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
277f0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
27800 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
27810 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
27820 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
27830 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
27840 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
27850 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
27860 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
27870 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
27880 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
27890 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
278a0 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
278b0 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
278c0 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
278d0 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
278e0 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
278f0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
27900 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
27910 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
27920 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
27930 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
27940 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
27950 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
27960 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
27970 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
27980 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
27990 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
279a0 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
279b0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
279c0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
279d0 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
279e0 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
279f0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
27a00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
27a10 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
27a20 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
27a30 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
27a40 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
27a50 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
27a60 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
27a70 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
27a80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
27a90 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
27aa0 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
27ab0 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
27ac0 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
27ad0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27ae0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
27af0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
27b00 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
27b10 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
27b20 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
27b30 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
27b40 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
27b50 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
27b60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
27b70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
27b80 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
27b90 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
27ba0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
27bb0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
27bc0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
27bd0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
27be0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
27bf0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
27c00 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
27c10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
27c20 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
27c30 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
27c40 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
27c50 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
27c60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
27c70 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
27c80 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
27c90 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
27ca0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
27cb0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
27cc0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
27cd0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
27ce0 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
27cf0 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
27d00 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
27d10 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
27d20 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
27d30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27d40 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
27d50 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
27d60 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
27d70 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
27d80 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
27d90 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
27da0 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
27db0 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
27dc0 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
27dd0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
27de0 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
27df0 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
27e00 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
27e10 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
27e20 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
27e30 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
27e40 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
27e50 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
27e60 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
27e70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
27e80 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
27e90 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
27ea0 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
27eb0 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
27ec0 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
27ed0 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
27ee0 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
27ef0 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
27f00 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
27f10 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
27f20 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
27f30 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
27f40 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
27f50 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
27f60 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
27f70 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
27f80 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
27f90 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
27fa0 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
27fb0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
27fc0 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
27fd0 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
27fe0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
27ff0 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
28000 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
28010 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
28020 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
28030 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
28040 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
28050 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
28060 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
28070 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
28080 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
28090 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
280a0 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
280b0 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
280c0 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
280d0 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
280e0 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
280f0 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
28100 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
28110 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
28120 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
28130 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
28140 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
28150 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
28160 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
28170 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
28180 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
28190 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
281a0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
281b0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
281c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
281d0 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65  ecltype16(sqlite
281e0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
281f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
28200 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
28210 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41  tatement.**.** A
28220 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
28230 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
28240 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
28250 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73  ing either.** [s
28260 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28270 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
28280 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
28290 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
282a0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
282b0 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
282c0 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
282d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
282e0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
282f0 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
28300 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
28310 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
28320 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
28330 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
28340 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
28350 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
28360 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
28370 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
28380 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
28390 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
283a0 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
283b0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
283c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
283d0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
283e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
283f0 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
28400 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
28410 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
28420 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
28430 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28440 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
28450 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
28460 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
28470 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
28480 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
28490 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
284a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
284b0 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
284c0 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
284d0 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79  * ^In the legacy
284e0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
284f0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c  return value wil
28500 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c  l be either [SQL
28510 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53  ITE_BUSY],.** [S
28520 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
28530 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
28540 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
28550 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
28560 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22  * ^With the "v2"
28570 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20   interface, any 
28580 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65  of the other [re
28590 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a  sult codes] or.*
285a0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
285b0 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20  lt codes] might 
285c0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77  be returned as w
285d0 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ell..**.** ^[SQL
285e0 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
285f0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
28600 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
28610 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
28620 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
28630 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
28640 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49   do its job.  ^I
28650 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
28660 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a  is a [COMMIT].**
28670 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69   or occurs outsi
28680 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69  de of an explici
28690 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
286a0 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72  hen you can retr
286b0 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  y the.** stateme
286c0 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  nt.  If the stat
286d0 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b  ement is not a [
286e0 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75  COMMIT] and occu
286f0 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20  rs within an.** 
28700 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
28710 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
28720 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
28730 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
28740 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
28750 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ng..**.** ^[SQLI
28760 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
28770 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
28780 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
28790 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
287a0 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
287b0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
287c0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
287d0 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
287e0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
287f0 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
28800 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
28810 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
28820 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
28830 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
28840 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
28850 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e..**.** ^If the
28860 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
28870 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
28880 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
28890 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
288a0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
288b0 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
288c0 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
288d0 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
288e0 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
288f0 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
28900 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
28910 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
28920 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
28930 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
28940 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
28950 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
28960 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
28970 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
28980 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d   ^[SQLITE_ERROR]
28990 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
289a0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
289b0 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
289c0 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
289d0 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
289e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
289f0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
28a00 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
28a10 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
28a20 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
28a30 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
28a40 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
28a50 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  ()]..** ^With th
28a60 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
28a70 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
28a80 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
28a90 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
28aa0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
28ab0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
28ac0 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
28ad0 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
28ae0 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
28af0 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
28b00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
28b10 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
28b20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28b30 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76  nt].  ^In the "v
28b40 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
28b50 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
28b60 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
28b70 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
28b80 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
28b90 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
28ba0 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
28bb0 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
28bc0 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
28bd0 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
28be0 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
28bf0 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
28c00 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
28c10 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
28c20 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
28c30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
28c40 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
28c50 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
28c60 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
28c70 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
28c80 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
28c90 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
28ca0 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
28cb0 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
28cc0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
28cd0 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
28ce0 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
28cf0 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
28d00 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
28d10 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
28d20 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f  * For all versio
28d30 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20  ns of SQLite up 
28d40 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67  to and including
28d50 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c   3.6.23.1, a cal
28d60 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
28d70 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65  _reset()] was re
28d80 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c  quired after sql
28d90 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75  ite3_step() retu
28da0 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a  rned anything.**
28db0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
28dc0 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20  ITE_ROW] before 
28dd0 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69  any subsequent i
28de0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  nvocation of.** 
28df0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
28e00 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65   Failure to rese
28e10 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
28e20 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a  tatement using .
28e30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
28e40 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c  t()] would resul
28e50 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  t in an [SQLITE_
28e60 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66  MISUSE] return f
28e70 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  rom.** sqlite3_s
28e80 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65  tep().  But afte
28e90 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33  r version 3.6.23
28ea0 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .1, sqlite3_step
28eb0 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c  () began.** call
28ec0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
28ed0 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61  et()] automatica
28ee0 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63  lly in this circ
28ef0 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a  umstance rather.
28f00 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e  ** than returnin
28f10 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  g [SQLITE_MISUSE
28f20 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20  ].  This is not 
28f30 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d  considered a com
28f40 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72  patibility.** br
28f50 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20  eak because any 
28f60 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74  application that
28f70 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61   ever receives a
28f80 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  n SQLITE_MISUSE 
28f90 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b  error.** is brok
28fa0 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e  en by definition
28fb0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
28fc0 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63  MIT_AUTORESET] c
28fd0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
28fe0 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  on.** can be use
28ff0 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65  d to restore the
29000 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
29010 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
29020 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
29030 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
29040 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
29050 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
29060 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
29070 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
29080 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
29090 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
290a0 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
290b0 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
290c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
290d0 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
290e0 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
290f0 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
29100 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
29110 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
29120 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
29130 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
29140 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
29150 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
29160 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
29170 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
29180 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
29190 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
291a0 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
291b0 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
291c0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
291d0 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
291e0 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
291f0 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
29200 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
29210 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
29220 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
29230 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
29240 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
29250 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
29260 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
29270 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
29280 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
29290 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
292a0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
292b0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
292c0 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
292d0 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
292e0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
292f0 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
29300 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
29310 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51  commended..*/.SQ
29320 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
29330 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
29340 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
29350 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
29360 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
29370 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a  a result set.**.
29380 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29390 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
293a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
293b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
293c0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
293d0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
293e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
293f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29400 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
29410 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29420 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
29430 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
29440 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
29450 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
29460 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29470 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
29480 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
29490 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
294a0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
294b0 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
294c0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
294d0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
294e0 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
294f0 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
29500 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
29510 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
29520 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
29530 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
29540 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
29550 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
29560 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
29570 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
29580 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
29590 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
295a0 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
295b0 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
295c0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
295d0 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
295e0 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
295f0 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
29600 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
29610 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
29620 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
29630 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
29640 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
29650 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
29660 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
29670 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
29680 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
29690 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
296a0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
296b0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
296c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
296d0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
296e0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
296f0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
29700 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
29710 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
29720 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
29730 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
29740 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
29750 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
29760 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
29770 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
29780 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
29790 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
297a0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
297b0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
297c0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
297d0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
297e0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
297f0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
29800 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
29810 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
29820 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
29830 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
29840 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
29850 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
29860 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
29870 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
29880 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
29890 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
298a0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
298b0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
298c0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
298d0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
298e0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
298f0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
29900 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
29910 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
29920 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
29930 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
29940 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
29950 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
29960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
29970 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
29980 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
29990 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
299a0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
299b0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
299c0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
299d0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
299e0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
299f0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
29a00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
29a10 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
29a20 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
29a30 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
29a40 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
29a50 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
29a60 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
29a70 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
29a80 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
29a90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
29aa0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
29ab0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
29ac0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
29ad0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
29ae0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
29af0 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
29b00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
29b10 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
29b20 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
29b30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
29b40 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
29b50 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
29b60 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
29b70 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
29b80 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
29b90 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
29ba0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
29bb0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
29bc0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
29bd0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
29be0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
29bf0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
29c00 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
29c10 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
29c20 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
29c30 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
29c40 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
29c50 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
29c60 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
29c70 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
29c80 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
29c90 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
29ca0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
29cb0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
29cc0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
29cd0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
29ce0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
29cf0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
29d00 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
29d10 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
29d20 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
29d30 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
29d40 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
29d50 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
29d60 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
29d70 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
29d80 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
29d90 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
29da0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
29db0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
29dc0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
29dd0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
29de0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
29df0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
29e00 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
29e10 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
29e20 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
29e30 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
29e40 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
29e50 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
29e60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
29e70 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
29e80 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
29e90 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
29ea0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
29eb0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
29ec0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
29ed0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
29ee0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
29ef0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29f00 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
29f10 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
29f20 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
29f30 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
29f40 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
29f50 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
29f60 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
29f70 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
29f80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29f90 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
29fa0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
29fb0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
29fc0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
29fd0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
29fe0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
29ff0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
2a000 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2a010 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
2a020 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2a030 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
2a040 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
2a050 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
2a060 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
2a070 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
2a080 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2a090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2a0a0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
2a0b0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
2a0c0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
2a0d0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
2a0e0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
2a0f0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
2a100 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
2a110 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
2a120 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2a130 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2a140 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
2a150 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
2a160 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
2a170 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
2a180 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
2a190 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
2a1a0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
2a1b0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
2a1c0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2a1d0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2a1e0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
2a1f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2a200 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
2a210 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2a220 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2a230 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2a240 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2a250 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2a260 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
2a270 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2a280 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
2a290 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2a2a0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
2a2b0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2a2c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2a2d0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2a2e0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2a2f0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2a300 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2a310 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2a320 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2a330 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2a340 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
2a350 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2a360 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2a370 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2a380 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2a390 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2a3a0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2a3b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2a3c0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2a3d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2a3e0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2a3f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
2a400 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2a410 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
2a420 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2a430 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2a440 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2a450 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2a460 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2a470 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
2a480 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2a490 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2a4a0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2a4b0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2a4c0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
2a4d0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2a4e0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2a4f0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2a500 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2a510 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2a520 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
2a530 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2a540 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2a550 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2a560 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
2a570 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2a580 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2a590 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2a5a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2a5b0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2a5c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2a5d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
2a5e0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2a5f0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
2a600 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2a610 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2a620 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
2a630 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2a640 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
2a650 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
2a660 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
2a670 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
2a680 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
2a690 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
2a6a0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2a6b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2a6c0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
2a6d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2a6e0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
2a6f0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
2a700 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
2a710 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2a720 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
2a730 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
2a740 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2a750 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2a760 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2a770 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
2a780 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
2a790 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
2a7a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
2a7b0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
2a7c0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
2a7d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2a7e0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
2a7f0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
2a800 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2a810 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  * ^The object re
2a820 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2a830 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2a840 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
2a850 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2a860 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
2a870 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
2a880 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2a890 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
2a8a0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
2a8b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2a8c0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2a8d0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2a8e0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
2a8f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2a900 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2a910 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2a920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2a930 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
2a940 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
2a950 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
2a960 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
2a970 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
2a980 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
2a990 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2a9a0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2a9b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2a9c0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
2a9d0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2a9e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
2a9f0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
2aa00 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2aa10 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
2aa20 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
2aa30 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
2aa40 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
2aa50 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
2aa60 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
2aa70 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
2aa80 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
2aa90 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
2aaa0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
2aab0 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
2aac0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
2aad0 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
2aae0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
2aaf0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
2ab00 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
2ab10 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
2ab20 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2ab30 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
2ab40 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
2ab50 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
2ab60 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
2ab70 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
2ab80 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
2ab90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2aba0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2abb0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2abc0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
2abd0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
2abe0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
2abf0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
2ac00 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2ac10 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2ac20 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
2ac30 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2ac40 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2ac50 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2ac60 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
2ac70 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2ac80 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2ac90 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2aca0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2acb0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
2acc0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
2acd0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
2ace0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2acf0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2ad00 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
2ad10 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2ad20 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2ad30 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
2ad40 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
2ad50 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2ad60 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2ad70 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  > Convert from f
2ad80 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a  loat to integer.
2ad90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2ada0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
2adb0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
2adc0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
2add0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2ade0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2adf0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2ae00 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45  ame as FLOAT->TE
2ae10 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
2ae20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
2ae30 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20  EGER   <td> Use 
2ae40 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
2ae50 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2ae60 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2ae70 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  Use atof().** <t
2ae80 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2ae90 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2aea0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
2aeb0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2aec0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2aed0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
2aee0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
2aef0 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
2af00 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2af10 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2af20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
2af30 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a  then use atof().
2af40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2af50 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
2af60 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
2af70 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
2af80 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
2af90 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
2afa0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  uote>)^.**.** Th
2afb0 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
2afc0 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
2afd0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
2afe0 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
2aff0 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
2b000 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
2b010 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
2b020 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
2b030 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
2b040 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
2b050 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
2b060 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
2b070 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
2b080 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
2b090 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
2b0a0 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
2b0b0 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
2b0c0 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
2b0d0 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
2b0e0 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
2b0f0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2b100 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
2b110 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
2b120 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
2b130 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2b140 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
2b150 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
2b160 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
2b170 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2b180 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
2b190 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
2b1a0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
2b1b0 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
2b1c0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
2b1d0 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
2b1e0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
2b1f0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
2b200 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2b210 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
2b220 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2b230 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
2b240 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b250 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2b260 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
2b270 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
2b280 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
2b290 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
2b2a0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
2b2b0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2b2c0 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
2b2d0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
2b2e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
2b2f0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2b300 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2b310 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2b320 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2b330 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2b340 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
2b350 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2b360 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2b370 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
2b380 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2b390 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2b3a0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2b3b0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
2b3c0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
2b3d0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
2b3e0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
2b3f0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
2b400 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
2b410 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
2b420 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
2b430 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
2b440 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
2b450 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
2b460 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
2b470 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
2b480 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
2b490 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
2b4a0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
2b4b0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
2b4c0 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
2b4d0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
2b4e0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
2b4f0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
2b500 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
2b510 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
2b520 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
2b530 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
2b540 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
2b550 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
2b560 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
2b570 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
2b580 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
2b590 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
2b5a0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
2b5b0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
2b5c0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2b5d0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
2b5e0 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
2b5f0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
2b600 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2b610 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
2b620 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2b630 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2b640 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2b650 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
2b660 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2b670 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2b680 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2b690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2b6a0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
2b6b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b6c0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
2b6d0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2b6e0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
2b6f0 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
2b700 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2b710 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
2b720 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
2b730 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2b740 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
2b750 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
2b760 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
2b770 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
2b780 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
2b790 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b7a0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2b7b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2b7c0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
2b7d0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
2b7e0 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
2b7f0 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
2b800 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2b810 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2b820 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
2b830 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2b840 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2b850 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
2b860 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
2b870 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2b880 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
2b890 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2b8a0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
2b8b0 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
2b8c0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
2b8d0 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
2b8e0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
2b8f0 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
2b900 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
2b910 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
2b920 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2b930 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2b940 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2b950 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
2b960 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
2b970 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
2b980 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
2b990 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
2b9a0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
2b9b0 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
2b9c0 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
2b9d0 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
2b9e0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
2b9f0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
2ba00 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
2ba10 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
2ba20 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
2ba30 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
2ba40 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
2ba50 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
2ba60 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
2ba70 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
2ba80 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
2ba90 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
2baa0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
2bab0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
2bac0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
2bad0 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
2bae0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
2baf0 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
2bb00 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
2bb10 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
2bb20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2bb30 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
2bb40 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
2bb50 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
2bb60 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2bb70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2bb80 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2bb90 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2bba0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2bbb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2bbc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2bbd0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2bbe0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2bbf0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2bc00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2bc10 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2bc20 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69  _API double sqli
2bc30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
2bc40 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2bc50 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2bc60 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2bc70 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
2bc80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2bc90 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2bca0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
2bcb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bcc0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2bcd0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2bce0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2bcf0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2bd00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2bd10 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2bd20 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2bd30 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2bd40 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2bd50 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
2bd60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2bd70 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2bd80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2bd90 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2bda0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2bdb0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
2bdc0 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
2bdd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2bde0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2bdf0 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
2be00 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
2be10 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
2be20 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
2be30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2be40 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
2be50 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
2be60 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
2be70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2be80 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
2be90 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
2bea0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
2beb0 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
2bec0 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
2bed0 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
2bee0 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
2bef0 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
2bf00 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2bf10 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
2bf20 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
2bf30 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
2bf40 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
2bf50 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
2bf60 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
2bf70 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
2bf80 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
2bf90 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2bfa0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2bfb0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
2bfc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2bfd0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
2bfe0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
2bff0 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
2c000 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
2c010 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
2c020 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c030 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
2c040 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
2c050 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
2c060 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
2c070 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
2c080 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
2c090 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
2c0a0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
2c0b0 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
2c0c0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
2c0d0 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
2c0e0 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
2c0f0 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
2c100 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
2c110 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2c120 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
2c130 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
2c140 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
2c150 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
2c160 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
2c170 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
2c180 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
2c190 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
2c1a0 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
2c1b0 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
2c1c0 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
2c1d0 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
2c1e0 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
2c1f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
2c200 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
2c210 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
2c220 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
2c230 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2c240 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
2c250 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
2c260 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
2c270 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
2c280 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
2c290 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
2c2a0 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
2c2b0 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ption..*/.SQLITE
2c2c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2c2d0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
2c2e0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2c2f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c300 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
2c310 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2c320 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
2c330 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
2c340 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
2c350 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
2c360 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2c370 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
2c380 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2c390 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
2c3a0 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
2c3b0 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
2c3c0 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
2c3d0 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
2c3e0 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
2c3f0 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
2c400 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
2c410 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
2c420 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
2c430 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
2c440 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
2c450 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
2c460 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
2c470 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
2c480 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2c490 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
2c4a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2c4b0 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
2c4c0 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
2c4d0 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
2c4e0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
2c4f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2c500 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2c510 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2c520 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2c530 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
2c540 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2c550 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2c560 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
2c570 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
2c580 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
2c590 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
2c5a0 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
2c5b0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2c5c0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
2c5d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
2c5e0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2c5f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2c600 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2c610 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c620 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
2c630 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
2c640 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2c650 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
2c660 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2c670 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2c680 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
2c690 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2c6a0 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
2c6b0 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
2c6c0 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
2c6d0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
2c6e0 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
2c6f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c700 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50   S..*/.SQLITE_AP
2c710 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  I int sqlite3_re
2c720 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
2c730 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2c740 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
2c750 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
2c760 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
2c770 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
2c780 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2c790 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
2c7a0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2c7b0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2c7c0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
2c7d0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2c7e0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2c7f0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
2c800 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
2c810 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
2c820 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
2c830 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2c840 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
2c850 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
2c860 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2c870 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
2c880 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2c890 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
2c8a0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2c8b0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
2c8c0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
2c8d0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
2c8e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
2c8f0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
2c900 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
2c910 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2c920 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
2c930 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
2c940 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
2c950 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
2c960 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
2c970 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
2c980 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
2c990 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2c9a0 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
2c9b0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2c9c0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
2c9d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2c9e0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
2c9f0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
2ca00 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
2ca10 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
2ca20 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
2ca30 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
2ca40 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
2ca50 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
2ca60 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2ca70 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
2ca80 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
2ca90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2caa0 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
2cab0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2cac0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2cad0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
2cae0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2caf0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
2cb00 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
2cb10 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
2cb20 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
2cb30 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
2cb40 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
2cb50 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
2cb60 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
2cb70 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
2cb80 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
2cb90 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
2cba0 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
2cbb0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
2cbc0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
2cbd0 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
2cbe0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
2cbf0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
2cc00 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
2cc10 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
2cc20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
2cc30 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
2cc40 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2cc50 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
2cc60 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2cc70 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
2cc80 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
2cc90 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2cca0 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
2ccb0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
2ccc0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
2ccd0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2cce0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
2ccf0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
2cd00 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
2cd10 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
2cd20 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
2cd30 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2cd40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2cd50 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
2cd60 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
2cd70 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
2cd80 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
2cd90 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
2cda0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2cdb0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2cdc0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
2cdd0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
2cde0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
2cdf0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
2ce00 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
2ce10 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
2ce20 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
2ce30 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
2ce40 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51  eters.  Every SQ
2ce50 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
2ce60 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62  mentation must b
2ce70 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
2ce80 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  * with UTF-8, UT
2ce90 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
2cea0 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
2ceb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
2cec0 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
2ced0 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
2cee0 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
2cef0 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70  nother.  ^An app
2cf00 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20  lication may.** 
2cf10 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2cf20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2cf30 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
2cf40 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
2cf50 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
2cf60 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2cf70 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
2cf80 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
2cf90 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
2cfa0 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
2cfb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2cfc0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2cfd0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
2cfe0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
2cff0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
2d000 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
2d010 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
2d020 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
2d030 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
2d040 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
2d050 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2d060 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
2d070 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
2d080 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
2d090 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
2d0a0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
2d0b0 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
2d0c0 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  NY]..**.** ^(The
2d0d0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2d0e0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
2d0f0 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
2d100 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2d110 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
2d120 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
2d130 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
2d140 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2d150 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
2d160 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2d170 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69  , seventh and ei
2d180 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  ghth parameters,
2d190 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
2d1a0 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
2d1b0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
2d1c0 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
2d1d0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2d1e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2d1f0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2d200 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
2d210 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2d220 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2d230 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
2d240 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
2d250 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
2d260 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  s must be passed
2d270 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
2d280 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
2d290 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72  meters. ^An aggr
2d2a0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2d2b0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2d2c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2d2d0 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
2d2e0 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f  inal and NULL po
2d2f0 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61  inter must be pa
2d300 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
2d310 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
2d320 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
2d330 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2d340 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70  ate, pass NULL p
2d350 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20  ointers for all 
2d360 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
2d370 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
2d380 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
2d390 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2d3a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2d3b0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
2d3c0 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
2d3d0 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
2d3e0 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
2d3f0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2d400 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
2d410 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
2d420 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
2d430 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
2d440 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
2d450 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
2d460 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
2d470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
2d480 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
2d490 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
2d4a0 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
2d4b0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
2d4c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d4d0 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
2d4e0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
2d4f0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
2d500 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
2d510 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
2d520 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
2d530 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
2d540 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
2d550 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
2d560 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
2d570 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
2d580 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
2d590 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2d5a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d5b0 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
2d5c0 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
2d5d0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
2d5e0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2d5f0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2d600 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
2d610 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
2d620 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
2d630 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
2d640 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
2d650 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
2d660 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2d670 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
2d680 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
2d690 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2d6a0 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
2d6b0 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
2d6c0 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
2d6d0 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
2d6e0 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
2d6f0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2d700 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
2d710 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
2d720 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
2d730 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
2d740 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
2d750 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2d760 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
2d770 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
2d780 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
2d790 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2d7a0 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
2d7b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2d7c0 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
2d7d0 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
2d7e0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
2d7f0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
2d800 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
2d810 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
2d820 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2d830 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
2d840 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
2d850 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
2d860 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
2d870 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
2d880 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2d890 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
2d8a0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
2d8b0 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
2d8c0 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
2d8d0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
2d8e0 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
2d8f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2d900 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
2d910 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
2d920 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2d930 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
2d940 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
2d950 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
2d960 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
2d970 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
2d980 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
2d990 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d9a0 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
2d9b0 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
2d9c0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2d9d0 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
2d9e0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
2d9f0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
2da00 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2da10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2da20 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2da30 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2da40 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2da50 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2da60 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2da70 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2da80 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2da90 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2daa0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2dab0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2dac0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2dad0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2dae0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2daf0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2db00 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49  ontext*).);.SQLI
2db10 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2db20 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2db30 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
2db40 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
2db50 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
2db60 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2db70 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2db80 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2db90 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2dba0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2dbb0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2dbc0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2dbd0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2dbe0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2dbf0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2dc00 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
2dc10 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
2dc20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2dc30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2dc40 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
2dc50 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
2dc60 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
2dc70 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
2dc80 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
2dc90 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
2dca0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
2dcb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2dcc0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2dcd0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2dce0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
2dcf0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2dd00 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2dd10 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
2dd20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2dd30 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
2dd40 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
2dd50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2dd60 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
2dd70 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2dd80 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
2dd90 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
2dda0 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
2ddb0 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
2ddc0 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
2ddd0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
2dde0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2ddf0 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64  8           1.#d
2de00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2de10 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64  16LE        2.#d
2de20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2de30 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64  16BE        3.#d
2de40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2de50 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
2de60 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
2de70 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
2de80 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
2de90 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
2dea0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
2deb0 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20  e_function only 
2dec0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2ded0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
2dee0 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
2def0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2df00 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
2df10 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
2df20 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
2df30 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
2df40 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
2df50 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
2df60 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
2df70 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
2df80 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
2df90 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
2dfa0 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
2dfb0 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
2dfc0 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
2dfd0 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
2dfe0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
2dff0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
2e000 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
2e010 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
2e020 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20   help encourage 
2e030 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a  people to avoid.
2e040 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66  ** using these f
2e050 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65  unctions, we are
2e060 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65   not going to te
2e070 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79  ll you what they
2e080 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
2e090 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
2e0a0 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50  ECATED.SQLITE_AP
2e0b0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
2e0c0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2e0d0 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
2e0e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2e0f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
2e100 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2e110 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
2e120 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
2e130 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
2e140 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2e150 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
2e160 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
2e170 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
2e180 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
2e190 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
2e1a0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2e1b0 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
2e1c0 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
2e1d0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
2e1e0 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
2e1f0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
2e200 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
2e210 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
2e220 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2e230 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
2e240 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
2e250 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
2e260 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65  nt),void*,sqlite
2e270 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
2e280 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e290 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
2e2a0 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74  Function Paramet
2e2b0 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20  er Values.**.** 
2e2c0 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
2e2d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2e2e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2e2f0 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
2e300 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
2e310 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
2e320 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
2e330 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
2e340 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
2e350 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2e360 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ate..**.** The x
2e370 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
2e380 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
2e390 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
2e3a0 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
2e3b0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
2e3c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2e3d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2e3e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2e3f0 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
2e400 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
2e410 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
2e420 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2e430 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
2e440 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
2e450 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
2e460 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
2e470 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
2e480 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2e490 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2e4a0 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
2e4b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2e4c0 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
2e4d0 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
2e4e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2e4f0 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
2e500 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
2e510 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
2e520 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
2e530 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2e540 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
2e550 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
2e560 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
2e570 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2e580 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
2e590 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
2e5a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
2e5b0 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
2e5c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2e5d0 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
2e5e0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
2e5f0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2e600 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2e610 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
2e620 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2e630 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
2e640 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
2e650 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
2e660 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
2e670 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
2e680 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e690 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
2e6a0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
2e6b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2e6c0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
2e6d0 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
2e6e0 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
2e6f0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2e700 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
2e710 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
2e720 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
2e730 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
2e740 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
2e750 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
2e760 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
2e770 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
2e780 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
2e790 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
2e7a0 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
2e7b0 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
2e7c0 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
2e7d0 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
2e7e0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
2e7f0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
2e800 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2e810 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
2e820 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
2e830 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
2e840 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
2e850 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
2e860 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
2e870 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
2e880 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2e890 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
2e8a0 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
2e8b0 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
2e8c0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2e8d0 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
2e8e0 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
2e8f0 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
2e900 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
2e910 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
2e920 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
2e930 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
2e940 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
2e950 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
2e960 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
2e970 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
2e980 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
2e990 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
2e9a0 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
2e9b0 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
2e9c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
2e9d0 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
2e9e0 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
2e9f0 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
2ea00 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
2ea10 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
2ea20 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
2ea30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2ea40 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
2ea50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2ea60 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
2ea70 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
2ea80 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
2ea90 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
2eaa0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
2eab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2eac0 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
2ead0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2eae0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2eaf0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
2eb00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2eb10 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
2eb20 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2eb30 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
2eb40 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2eb50 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
2eb60 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2eb70 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
2eb80 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2eb90 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2eba0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
2ebb0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2ebc0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2ebd0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2ebe0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2ebf0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2ec00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
2ec10 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
2ec20 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2ec30 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  PI double sqlite
2ec40 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
2ec50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2ec60 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2ec70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2ec80 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2ec90 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
2eca0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2ecb0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
2ecc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2ecd0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2ece0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2ecf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2ed00 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
2ed10 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
2ed20 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2ed30 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2ed40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2ed50 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2ed60 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2ed70 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
2ed80 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2ed90 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2eda0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2edb0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
2edc0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
2edd0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2ede0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
2edf0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2ee00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2ee10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
2ee20 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
2ee30 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
2ee40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2ee50 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
2ee60 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
2ee70 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
2ee80 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
2ee90 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
2eea0 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
2eeb0 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
2eec0 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
2eed0 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
2eee0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2eef0 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
2ef00 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2ef10 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
2ef20 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
2ef30 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2ef40 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2ef50 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
2ef60 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
2ef70 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
2ef80 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
2ef90 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2efa0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
2efb0 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
2efc0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
2efd0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
2efe0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2eff0 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
2f000 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
2f010 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
2f020 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
2f030 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
2f040 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
2f050 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2f060 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
2f070 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
2f080 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
2f090 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
2f0a0 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
2f0b0 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
2f0c0 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
2f0d0 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
2f0e0 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
2f0f0 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
2f100 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
2f110 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
2f120 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
2f130 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2f140 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
2f150 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
2f160 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
2f170 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
2f180 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
2f190 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
2f1a0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2f1b0 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
2f1c0 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
2f1d0 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
2f1e0 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
2f1f0 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
2f200 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
2f210 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2f220 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2f230 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2f240 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20  if N is.** less 
2f250 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
2f260 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65   zero or if a me
2f270 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72  mory allocate er
2f280 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
2f290 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
2f2a0 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
2f2b0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
2f2c0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2f2d0 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
2f2e0 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
2f2f0 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
2f300 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
2f310 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
2f320 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
2f330 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2f340 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
2f350 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2f360 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
2f370 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
2f380 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
2f390 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
2f3a0 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
2f3b0 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  ocation.)^.**.**
2f3c0 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74   ^SQLite automat
2f3d0 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
2f3e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
2f3f0 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
2f400 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2f410 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67  xt() when the ag
2f420 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f  gregate query co
2f430 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
2f440 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2f450 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70  er must be a cop
2f460 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
2f470 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
2f480 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
2f490 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
2f4a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2f4b0 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70  .** to the xStep
2f4c0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
2f4d0 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
2f4e0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2f4f0 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
2f500 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
2f510 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
2f520 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2f530 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2f540 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
2f550 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2f560 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2f570 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
2f580 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
2f590 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
2f5a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2f5b0 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
2f5c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
2f5d0 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
2f5e0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
2f5f0 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
2f600 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2f610 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2f620 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2f630 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
2f640 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
2f650 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
2f660 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2f670 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f680 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2f690 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2f6a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2f6b0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2f6c0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2f6d0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2f6e0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2f6f0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2f700 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
2f710 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2f720 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2f730 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2f740 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f750 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
2f760 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
2f770 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
2f780 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2f790 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f7a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f7b0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2f7c0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
2f7d0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
2f7e0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2f7f0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
2f800 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2f810 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2f820 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
2f830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f840 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
2f850 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
2f860 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2f870 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
2f880 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2f890 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2f8a0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
2f8b0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
2f8c0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
2f8d0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2f8e0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
2f8f0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
2f900 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
2f910 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
2f920 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2f930 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f940 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
2f950 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
2f960 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
2f970 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
2f980 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
2f990 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
2f9a0 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
2f9b0 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
2f9c0 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
2f9d0 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
2f9e0 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
2f9f0 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
2fa00 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2fa10 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
2fa20 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
2fa30 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
2fa40 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
2fa50 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
2fa60 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
2fa70 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
2fa80 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
2fa90 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
2faa0 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
2fab0 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
2fac0 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
2fad0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
2fae0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
2faf0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
2fb00 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
2fb10 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
2fb20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2fb30 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
2fb40 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
2fb50 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
2fb60 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
2fb70 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
2fb80 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
2fb90 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
2fba0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
2fbb0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2fbc0 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
2fbd0 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
2fbe0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
2fbf0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2fc00 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
2fc10 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
2fc20 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
2fc30 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2fc40 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2fc50 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2fc60 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
2fc70 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
2fc80 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
2fc90 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
2fca0 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
2fcb0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
2fcc0 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
2fcd0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2fce0 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20  unction. ^If no 
2fcf0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
2fd00 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
2fd10 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
2fd20 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
2fd30 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
2fd40 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2fd50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
2fd60 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
2fd70 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
2fd80 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
2fd90 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
2fda0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
2fdb0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
2fdc0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2fdd0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
2fde0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
2fdf0 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
2fe00 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
2fe10 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
2fe20 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
2fe30 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
2fe40 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
2fe50 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2fe60 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2fe70 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
2fe80 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2fe90 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2fea0 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
2feb0 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
2fec0 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
2fed0 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e   destroyed..** ^
2fee0 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
2fef0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
2ff00 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2ff10 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ctor.** function
2ff20 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
2ff30 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2ff40 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2ff50 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
2ff60 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65  etadata when the
2ff70 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
2ff80 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
2ff90 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20  r changes.** or 
2ffa0 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  when the SQL sta
2ffb0 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73  tement completes
2ffc0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
2ffd0 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  s first..**.** S
2ffe0 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
2fff0 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75   call the destru
30000 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65  ctor and drop me
30010 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a  tadata on any.**
30020 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
30030 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
30040 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e  y time.  ^The on
30050 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
30060 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
30070 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
30080 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
30090 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
300a0 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  pped..**.** ^(In
300b0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
300c0 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
300d0 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
300e0 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
300f0 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
30100 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
30110 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
30120 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
30130 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
30140 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29  d [parameters].)
30150 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ^.**.** These ro
30160 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
30170 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
30180 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
30190 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
301a0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
301b0 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
301c0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
301d0 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
301e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
301f0 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t N);.SQLITE_API
30200 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65   void sqlite3_se
30210 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
30220 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
30230 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
30240 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
30250 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
30260 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
30270 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
30280 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
30290 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
302a0 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
302b0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
302c0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
302d0 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
302e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
302f0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
30300 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
30310 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
30320 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
30330 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
30340 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
30350 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
30360 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
30370 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
30380 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
30390 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
303a0 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
303b0 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
303c0 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
303d0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
303e0 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
303f0 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
30400 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
30410 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
30420 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
30430 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
30440 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
30450 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
30460 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
30470 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
30480 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
30490 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
304a0 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
304b0 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
304c0 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
304d0 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
304e0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
304f0 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
30500 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
30510 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
30520 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
30530 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
30540 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
30550 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
30560 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
30570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30580 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
30590 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
305a0 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
305b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
305c0 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
305d0 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
305e0 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
305f0 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
30600 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
30610 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
30620 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30630 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
30640 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30650 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
30660 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
30670 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
30680 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
30690 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
306a0 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
306b0 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
306c0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
306d0 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
306e0 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
306f0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
30700 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30710 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
30720 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
30730 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
30740 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
30750 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
30760 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30770 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
30780 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
30790 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
307a0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
307b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
307c0 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
307d0 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
307e0 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
307f0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
30800 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
30810 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
30820 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
30830 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
30840 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
30850 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
30860 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
30870 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
30880 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
30890 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
308a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
308b0 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
308c0 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
308d0 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
308e0 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
308f0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
30900 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
30910 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
30920 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
30930 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
30940 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
30950 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
30960 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30970 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
30980 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
30990 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
309a0 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
309b0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
309c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
309d0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
309e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
309f0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
30a00 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
30a10 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
30a20 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
30a30 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
30a40 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
30a50 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
30a60 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
30a70 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
30a80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30a90 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
30aa0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
30ab0 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
30ac0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
30ad0 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
30ae0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
30af0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
30b00 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
30b10 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
30b20 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
30b30 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
30b40 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
30b50 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
30b60 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
30b70 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
30b80 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
30b90 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
30ba0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
30bb0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
30bc0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
30bd0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
30be0 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
30bf0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
30c00 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
30c10 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
30c20 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
30c30 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
30c40 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
30c50 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
30c60 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
30c70 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
30c80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30c90 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
30ca0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
30cb0 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
30cc0 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
30cd0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
30ce0 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
30cf0 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
30d00 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
30d10 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30d20 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
30d30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30d40 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
30d50 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
30d60 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
30d70 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
30d80 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
30d90 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
30da0 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
30db0 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
30dc0 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
30dd0 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
30de0 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
30df0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
30e00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30e10 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
30e20 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
30e30 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
30e40 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
30e50 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
30e60 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
30e70 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
30e80 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
30e90 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
30ea0 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
30eb0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
30ec0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
30ed0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
30ee0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30ef0 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
30f00 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
30f10 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
30f20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30f30 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
30f40 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
30f50 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
30f60 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
30f70 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
30f80 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
30f90 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
30fa0 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
30fb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
30fc0 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
30fd0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
30fe0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
30ff0 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
31000 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
31010 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
31020 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
31030 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31040 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
31050 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
31060 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
31070 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31080 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
31090 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
310a0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
310b0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
310c0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
310d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
310e0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
310f0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
31100 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
31110 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
31120 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
31130 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
31140 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
31150 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
31160 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
31170 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
31180 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
31190 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
311a0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
311b0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
311c0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
311d0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
311e0 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
311f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31200 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
31210 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31220 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
31230 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31240 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
31250 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
31260 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
31270 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
31280 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
31290 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
312a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
312b0 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
312c0 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
312d0 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
312e0 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
312f0 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
31300 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
31310 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
31320 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
31330 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51  ectively..** ^SQ
31340 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
31350 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
31360 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
31370 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
31380 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
31390 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
313a0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
313b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
313c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
313d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
313e0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
313f0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
31400 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
31410 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
31420 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
31430 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
31440 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
31450 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
31460 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
31470 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
31480 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
31490 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
314a0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
314b0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
314c0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
314d0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
314e0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
314f0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
31500 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
31510 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
31520 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
31530 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20  ion result.  If 
31540 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
31550 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  r is non-negativ
31560 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75  e, then it.** mu
31570 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
31580 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73  ffset into the s
31590 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20  tring where the 
315a0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
315b0 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69  ould.** appear i
315c0 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  f the string whe
315d0 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65  re NUL terminate
315e0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
315f0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a  haracters occur.
31600 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  ** in the string
31610 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65   at a byte offse
31620 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74  t that is less t
31630 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  han the value of
31640 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61   the 3rd.** para
31650 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
31660 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
31670 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d   will contain em
31680 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20  bedded NULs and 
31690 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66  the.** result of
316a0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65   expressions ope
316b0 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67  rating on string
316c0 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  s with embedded 
316d0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
316e0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  d..** ^If the 4t
316f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
31700 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31710 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
31720 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
31730 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
31740 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
31750 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
31760 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
31770 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
31780 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
31790 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
317a0 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
317b0 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
317c0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
317d0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
317e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
317f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31800 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
31810 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
31820 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
31830 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
31840 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
31850 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
31860 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
31870 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
31880 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
31890 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
318a0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
318b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
318c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
318d0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
318e0 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
318f0 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
31900 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
31910 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
31920 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
31930 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
31940 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31950 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
31960 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
31970 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
31980 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
31990 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
319a0 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
319b0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
319c0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
319d0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
319e0 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
319f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
31a00 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
31a10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31a20 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
31a30 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
31a40 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
31a50 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
31a60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
31a70 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
31a80 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
31a90 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
31aa0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
31ab0 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
31ac0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
31ad0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
31ae0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
31af0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
31b00 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
31b10 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
31b20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
31b30 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
31b40 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
31b50 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
31b60 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
31b70 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
31b80 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
31b90 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
31ba0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
31bb0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
31bc0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
31bd0 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
31be0 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
31bf0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
31c00 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
31c10 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
31c20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
31c30 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
31c40 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
31c50 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
31c60 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
31c70 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
31c80 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
31c90 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
31ca0 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
31cb0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
31cc0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
31cd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31ce0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
31cf0 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
31d00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
31d10 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
31d20 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
31d30 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ned..*/.SQLITE_A
31d40 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
31d50 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
31d60 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
31d70 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
31d80 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
31d90 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
31da0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31db0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
31dc0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
31dd0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
31de0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
31df0 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
31e00 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
31e10 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  har*, int);.SQLI
31e20 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
31e30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31e40 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
31e50 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
31e60 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
31e70 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
31e80 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
31e90 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
31ea0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
31eb0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
31ec0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
31ed0 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
31ee0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
31ef0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31f00 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
31f10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31f20 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
31f30 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
31f40 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
31f50 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
31f60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
31f70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
31f80 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
31f90 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
31fa0 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f  _int64);.SQLITE_
31fb0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
31fc0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c  _result_null(sql
31fd0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
31fe0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
31ff0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32000 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
32010 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
32020 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
32030 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
32040 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
32050 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
32060 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32070 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
32080 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
32090 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
320a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
320b0 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
320c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
320d0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
320e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
320f0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
32100 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32110 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
32120 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
32130 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
32140 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
32150 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
32160 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
32170 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32180 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
32190 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
321a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
321b0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
321c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
321d0 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
321e0 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
321f0 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
32200 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ences.**.** ^The
32210 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64  se functions add
32220 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64  , remove, or mod
32230 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e  ify a [collation
32240 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  ] associated.** 
32250 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
32260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
32270 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
32280 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
32290 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
322a0 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
322b0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
322c0 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
322d0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
322e0 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
322f0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
32300 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
32310 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
32320 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
32330 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  er for sqlite3_c
32340 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
32350 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  6()..** ^Collati
32360 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f  on names that co
32370 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f  mpare equal acco
32380 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65  rding to [sqlite
32390 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72  3_strnicmp()] ar
323a0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
323b0 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e  to be the same n
323c0 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ame..**.** ^(The
323d0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
323e0 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20  (eTextRep) must 
323f0 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
32400 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e  nstants:.** <ul>
32410 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
32420 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _UTF8],.** <li> 
32430 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
32440 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
32450 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c  E_UTF16BE],.** <
32460 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
32470 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  6], or.** <li> [
32480 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
32490 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29  GNED]..** </ul>)
324a0 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52  ^.** ^The eTextR
324b0 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65  ep argument dete
324c0 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64  rmines the encod
324d0 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70  ing of strings p
324e0 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  assed.** to the 
324f0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
32500 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61  on callback, xCa
32510 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
32520 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61  [SQLITE_UTF16] a
32530 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  nd [SQLITE_UTF16
32540 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73  _ALIGNED] values
32550 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a   for eTextRep.**
32560 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74   force strings t
32570 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20  o be UTF16 with 
32580 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
32590 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  r..** ^The [SQLI
325a0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
325b0 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78  ] value for eTex
325c0 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69  tRep forces stri
325d0 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20  ngs to begin.** 
325e0 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20  on an even byte 
325f0 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e  address..**.** ^
32600 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
32610 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e  ent, pArg, is an
32620 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
32630 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  a pointer that i
32640 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f  s passed.** thro
32650 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
32660 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
32670 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
32680 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
32690 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
326a0 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61  rgument, xCallba
326b0 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ck, is a pointer
326c0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
326d0 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e  g function..** ^
326e0 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69  Multiple collati
326f0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e  ng functions can
32700 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75   be registered u
32710 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  sing the same na
32720 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64  me but.** with d
32730 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
32740 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  p parameters and
32750 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
32760 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75   whichever.** fu
32770 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
32780 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
32790 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f   of data transfo
327a0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  rmation..** ^If 
327b0 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72  the xCallback ar
327c0 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74  gument is NULL t
327d0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  hen the collatin
327e0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  g function is.**
327f0 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e   deleted.  ^When
32800 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66   all collating f
32810 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20  unctions having 
32820 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  the same name ar
32830 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68  e deleted,.** th
32840 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  at collation is 
32850 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65  no longer usable
32860 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
32870 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
32880 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
32890 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20  ked with a copy 
328a0 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20  of the pArg .** 
328b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
328c0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74   pointer and wit
328d0 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e  h two strings in
328e0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
328f0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
32900 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
32910 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74  ent.  The collat
32920 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
32930 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69  t return an.** i
32940 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e  nteger that is n
32950 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f  egative, zero, o
32960 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66  r positive.** if
32970 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
32980 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20  g is less than, 
32990 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
329a0 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
329b0 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74  cond,.** respect
329c0 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74  ively.  A collat
329d0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
329e0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  t always return 
329f0 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a  the same answer.
32a00 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d  ** given the sam
32a10 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77  e inputs.  If tw
32a20 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74  o or more collat
32a30 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
32a40 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  e registered.** 
32a50 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c  to the same coll
32a60 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e  ation name (usin
32a70 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  g different eTex
32a80 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65  tRep values) the
32a90 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69  n all.** must gi
32aa0 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74  ve an equivalent
32ab0 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76   answer when inv
32ac0 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61  oked with equiva
32ad0 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  lent strings..**
32ae0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
32af0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65  unction must obe
32b00 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  y the following 
32b10 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61  properties for a
32b20 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c  ll.** strings A,
32b30 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a   B, and C:.**.**
32b40 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66   <ol>.** <li> If
32b50 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e   A==B then B==A.
32b60 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
32b70 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41   and B==C then A
32b80 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==C..** <li> If 
32b90 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74  A&lt;B THEN B&gt
32ba0 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ;A..** <li> If A
32bb0 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43  &lt;B and B&lt;C
32bc0 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a   then A&lt;C..**
32bd0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </ol>.**.** If 
32be0 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  a collating func
32bf0 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f  tion fails any o
32c00 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73  f the above cons
32c10 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74  traints and that
32c20 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  .** collating fu
32c30 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73  nction is  regis
32c40 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20  tered and used, 
32c50 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
32c60 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69  r of SQLite.** i
32c70 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
32c80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32c90 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32ca0 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
32cb0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32cc0 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77  collation().** w
32cd0 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e  ith the addition
32ce0 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72   that the xDestr
32cf0 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  oy callback is i
32d00 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77  nvoked on pArg w
32d10 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  hen.** the colla
32d20 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
32d30 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f   deleted..** ^Co
32d40 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
32d50 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68  s are deleted wh
32d60 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  en they are over
32d70 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a  ridden by later.
32d80 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ** calls to the 
32d90 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69  collation creati
32da0 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  on functions or 
32db0 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74  when the.** [dat
32dc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32dd0 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e  ] is closed usin
32de0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
32df0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ()]..**.** ^The 
32e00 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
32e10 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20  k is <u>not</u> 
32e20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a  called if the .*
32e30 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
32e40 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
32e50 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20  function fails. 
32e60 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
32e70 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  at invoke.** sql
32e80 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32e90 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20  ation_v2() with 
32ea0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74  a non-NULL xDest
32eb0 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  roy argument sho
32ec0 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68  uld .** check th
32ed0 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e  e return code an
32ee0 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  d dispose of the
32ef0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
32f00 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  a pointer.** the
32f10 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74  mselves rather t
32f20 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51  han expecting SQ
32f30 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74  Lite to deal wit
32f40 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a  h it for them..*
32f50 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72  * This is differ
32f60 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f  ent from every o
32f70 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
32f80 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f  rface.  The inco
32f90 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73  nsistency .** is
32fa0 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74   unfortunate but
32fb0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
32fc0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
32fd0 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a  ing backwards .*
32fe0 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  * compatibility.
32ff0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
33000 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61    [sqlite3_colla
33010 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61  tion_needed()] a
33020 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  nd [sqlite3_coll
33030 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
33040 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
33050 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
33060 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20  ate_collation(. 
33070 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
33080 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
33090 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
330a0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
330b0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
330c0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
330d0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
330e0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49  t void*).);.SQLI
330f0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
33100 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33110 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
33120 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
33130 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
33140 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
33150 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
33160 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
33170 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
33180 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
33190 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
331a0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53  roy)(void*).);.S
331b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
331c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
331d0 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
331e0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
331f0 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
33200 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
33210 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
33220 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
33230 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
33240 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
33250 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
33260 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
33270 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
33280 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
33290 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
332a0 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
332b0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
332c0 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
332d0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
332e0 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
332f0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
33300 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
33310 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
33320 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
33330 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
33340 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
33350 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
33360 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
33370 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
33380 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
33390 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
333a0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
333b0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
333c0 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
333d0 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
333e0 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
333f0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
33400 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
33410 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
33420 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
33430 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
33440 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
33450 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
33460 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
33470 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
33480 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
33490 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
334a0 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
334b0 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
334c0 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
334d0 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
334e0 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
334f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
33500 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
33510 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
33520 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
33530 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
33540 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
33550 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
33560 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
33570 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
33580 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
33590 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
335a0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
335b0 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
335c0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
335d0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
335e0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
335f0 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
33600 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
33610 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
33620 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
33630 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
33640 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
33650 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
33660 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
33670 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
33680 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
33690 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
336a0 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
336b0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
336c0 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
336d0 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
336e0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
336f0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
33700 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33710 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
33720 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
33730 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
33740 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33750 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53  tion_v2()]..*/.S
33760 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
33770 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33780 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
33790 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
337a0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
337b0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
337c0 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
337d0 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
337e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
337f0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a  ation_needed16(.
33800 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
33810 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28  oid*,.  void(*)(
33820 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
33830 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
33840 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66  t void*).);..#if
33850 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43  def SQLITE_HAS_C
33860 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  ODEC./*.** Speci
33870 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
33880 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
33890 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
338a0 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
338b0 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
338c0 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
338d0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
338e0 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
338f0 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
33900 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
33910 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
33920 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
33930 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
33940 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
33950 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
33960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
33970 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
33980 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
33990 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
339a0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
339b0 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
339c0 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
339d0 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
339e0 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
339f0 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
33a00 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
33a10 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
33a20 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
33a30 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
33a40 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
33a50 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
33a60 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
33a70 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
33a80 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
33a90 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
33aa0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
33ab0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
33ac0 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te..*/.SQLITE_AP
33ad0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  I int sqlite3_re
33ae0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
33af0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
33b00 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
33b10 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
33b20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
33b30 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
33b40 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
33b50 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
33b60 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
33b70 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
33b80 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
33b90 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
33ba0 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
33bb0 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
33bc0 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c  ill work..*/.SQL
33bd0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
33be0 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65  ite3_activate_se
33bf0 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  e(.  const char 
33c00 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
33c10 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
33c20 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
33c30 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51  endif..#ifdef SQ
33c40 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f  LITE_ENABLE_CERO
33c50 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  D./*.** Specify 
33c60 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
33c70 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64  ey for a CEROD d
33c80 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
33c90 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
33ca0 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f  none of the CERO
33cb0 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  D routines will 
33cc0 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  work..*/.SQLITE_
33cd0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
33ce0 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28  _activate_cerod(
33cf0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33d00 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
33d10 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
33d20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
33d30 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
33d40 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65  REF: Suspend Exe
33d50 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
33d60 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68  rt Time.**.** Th
33d70 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
33d80 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  ) function cause
33d90 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
33da0 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
33db0 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72  execution.** for
33dc0 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62   at least a numb
33dd0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
33de0 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
33df0 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
33e00 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72  *.** If the oper
33e10 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
33e20 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
33e30 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
33e40 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  h.** millisecond
33e50 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
33e60 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
33e70 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
33e80 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61  up to.** the nea
33e90 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65  rest second. The
33ea0 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
33eb0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
33ec0 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71   actually.** req
33ed0 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20  uested from the 
33ee0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
33ef0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
33f00 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c  .** ^SQLite impl
33f10 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65  ements this inte
33f20 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67  rface by calling
33f30 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a   the xSleep().**
33f40 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
33f50 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
33f60 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66  vfs] object.  If
33f70 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   the xSleep() me
33f80 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64  thod.** of the d
33f90 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f  efault VFS is no
33fa0 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f  t implemented co
33fb0 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20  rrectly, or not 
33fc0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a  implemented at.*
33fd0 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20  * all, then the 
33fe0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
33ff0 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20  te3_sleep() may 
34000 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65  deviate from the
34010 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20   description.** 
34020 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
34030 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 53  paragraphs..*/.S
34040 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
34050 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
34060 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34070 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  F: Name Of The F
34080 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
34090 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a  mporary Files.**
340a0 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
340b0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
340c0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
340d0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
340e0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
340f0 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
34100 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
34110 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61  then all tempora
34120 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61  ry files.** crea
34130 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68  ted by SQLite wh
34140 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
34150 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  -in [sqlite3_vfs
34160 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20   | VFS].** will 
34170 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61  be placed in tha
34180 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20  t directory.)^  
34190 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c  ^If this variabl
341a0 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  e.** is a NULL p
341b0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
341c0 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73  ite performs a s
341d0 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
341e0 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70  ropriate.** temp
341f0 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63  orary file direc
34200 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tory..**.** It i
34210 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
34220 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
34230 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f  s variable in mo
34240 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74  re than one.** t
34250 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e  hread at a time.
34260 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65    It is not safe
34270 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
34280 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
34290 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61  .** if a [databa
342a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
342b0 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20  s being used at 
342c0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e  the same time in
342d0 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74   a separate.** t
342e0 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20  hread..** It is 
342f0 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
34300 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
34310 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
34320 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
34330 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
34340 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
34350 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
34360 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
34370 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68  en called and th
34380 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
34390 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
343a0 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e  d.** thereafter.
343b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d  .**.** ^The [tem
343c0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
343d0 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f  y pragma] may mo
343e0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
343f0 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20  le and cause.** 
34400 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  it to point to m
34410 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
34420 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
34430 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d  loc].  ^Furtherm
34440 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d  ore,.** the [tem
34450 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
34460 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73  y pragma] always
34470 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e   assumes that an
34480 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74  y string.** that
34490 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70   this variable p
344a0 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64  oints to is held
344b0 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
344c0 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
344d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e  lite3_malloc] an
344e0 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79  d the pragma may
344f0 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65   attempt to free
34500 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   that memory.** 
34510 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
34520 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20  ree]..** Hence, 
34530 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  if this variable
34540 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72   is modified dir
34550 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74  ectly, either it
34560 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61   should be.** ma
34570 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20  de NULL or made 
34580 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
34590 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
345a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
345b0 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65  ].** or else the
345c0 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d   use of the [tem
345d0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
345e0 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64  y pragma] should
345f0 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a   be avoided..*/.
34600 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
34610 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
34620 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
34630 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
34640 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72  PI3REF: Test For
34650 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64   Auto-Commit Mod
34660 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  e.** KEYWORDS: {
34670 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d  autocommit mode}
34680 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34690 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
346a0 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  it() interface r
346b0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20  eturns non-zero 
346c0 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68  or.** zero if th
346d0 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65  e given database
346e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
346f0 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f  r is not in auto
34700 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20  commit mode,.** 
34710 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e  respectively.  ^
34720 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
34730 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  is on by default
34740 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
34750 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
34760 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73  d by a [BEGIN] s
34770 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75  tatement..** ^Au
34780 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
34790 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61   re-enabled by a
347a0 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
347b0 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
347c0 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
347d0 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
347e0 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
347f0 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
34800 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
34810 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69  action (errors i
34820 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
34830 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
34840 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  IOERR],.** [SQLI
34850 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49  TE_NOMEM], [SQLI
34860 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53  TE_BUSY], and [S
34870 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
34880 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72  ) then the.** tr
34890 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20  ansaction might 
348a0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
348b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
348c0 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a  he only way to.*
348d0 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68  * find out wheth
348e0 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  er SQLite automa
348f0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
34900 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
34910 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20  ion after.** an 
34920 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20  error is to use 
34930 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
34940 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
34950 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
34960 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
34970 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
34980 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
34990 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  on while this ro
349a0 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
349b0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  , then the retur
349c0 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e  n value.** is un
349d0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49  defined..*/.SQLI
349e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
349f0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
34a00 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
34a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
34a20 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20  nd The Database 
34a30 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70  Handle Of A Prep
34a40 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
34a50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34a60 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65  3_db_handle inte
34a70 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
34a80 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
34a90 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a  ection] handle.*
34aa0 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72  * to which a [pr
34ab0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34ac0 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65  ] belongs.  ^The
34ad0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34ae0 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e  ction].** return
34af0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62  ed by sqlite3_db
34b00 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73  _handle is the s
34b10 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
34b20 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61  nnection].** tha
34b30 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20  t was the first 
34b40 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
34b50 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
34b60 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28  are_v2()] call (
34b70 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  or its variants)
34b80 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74   that was used t
34b90 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20  o.** create the 
34ba0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
34bb0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f   first place..*/
34bc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
34bd0 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
34be0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
34bf0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
34c00 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54  PI3REF: Return T
34c10 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20  he Filename For 
34c20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
34c30 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
34c40 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65   sqlite3_db_file
34c50 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66  name(D,N) interf
34c60 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
34c70 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e  inter to a filen
34c80 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ame.** associate
34c90 64 20 77 69 74 68 20 64 61 74 61 62 61 73 65 20  d with database 
34ca0 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  N of connection 
34cb0 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61  D.  ^The main da
34cc0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68  tabase file.** h
34cd0 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69  as the name "mai
34ce0 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  n".  If there is
34cf0 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64 61 74   no attached dat
34d00 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64  abase N on the d
34d10 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
34d20 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64  ction D, or if d
34d30 61 74 61 62 61 73 65 20 4e 20 69 73 20 61 20 74  atabase N is a t
34d40 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d  emporary or in-m
34d50 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20  emory database, 
34d60 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  then.** a NULL p
34d70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
34d80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
34d90 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64  ilename returned
34da0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
34db0 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75 74 20  n is the output 
34dc0 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50  of the.** xFullP
34dd0 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f  athname method o
34de0 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49  f the [VFS].  ^I
34df0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
34e00 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
34e10 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75  ill be an absolu
34e20 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65  te pathname, eve
34e30 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  n if the filenam
34e40 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65  e used.** to ope
34e50 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  n the database o
34e60 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20  riginally was a 
34e70 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20  URI or relative 
34e80 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 53 51 4c  pathname..*/.SQL
34e90 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
34ea0 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66  ar *sqlite3_db_f
34eb0 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65 33 20  ilename(sqlite3 
34ec0 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  *db, const char 
34ed0 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  *zDbName);../*.*
34ee0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
34ef0 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72   the next prepar
34f00 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed statement.**.
34f10 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
34f20 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
34f30 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74  nter to the next
34f40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
34f50 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70  ment] after.** p
34f60 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20  Stmt associated 
34f70 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
34f80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
34f90 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69  Db.  ^If pStmt i
34fa0 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74  s NULL.** then t
34fb0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
34fc0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
34fd0 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65  to the first pre
34fe0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
34ff0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
35000 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
35010 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20  connection pDb. 
35020 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64   ^If no prepared
35030 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61   statement.** sa
35040 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64  tisfies the cond
35050 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72  itions of this r
35060 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72  outine, it retur
35070 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  ns NULL..**.** T
35080 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35090 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72  nection] pointer
350a0 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a   D in a call to.
350b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  ** [sqlite3_next
350c0 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74  _stmt(D,S)] must
350d0 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65   refer to an ope
350e0 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  n database.** co
350f0 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20  nnection and in 
35100 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20  particular must 
35110 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  not be a NULL po
35120 69 6e 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  inter..*/.SQLITE
35130 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 73 74 6d  _API sqlite3_stm
35140 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  t *sqlite3_next_
35150 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44  stmt(sqlite3 *pD
35160 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  b, sqlite3_stmt 
35170 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
35180 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74  CAPI3REF: Commit
35190 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f   And Rollback No
351a0 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
351b0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
351c0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
351d0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
351e0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
351f0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
35200 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
35210 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
35220 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54  ction is [COMMIT
35230 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a   | committed]..*
35240 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
35250 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
35260 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
35270 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
35280 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
35290 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
352a0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
352b0 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  n..** ^The sqlit
352c0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
352d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
352e0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
352f0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
35300 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
35310 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
35320 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20  on is [ROLLBACK 
35330 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a  | rolled back]..
35340 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
35350 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
35360 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
35370 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
35380 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
35390 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
353a0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
353b0 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41  dden..** ^The pA
353c0 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70  rg argument is p
353d0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f  assed through to
353e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
353f0 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
35400 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68  ck on a commit h
35410 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ook function ret
35420 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a  urns non-zero,.*
35430 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69  * then the commi
35440 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  t is converted i
35450 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
35460 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35470 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44  e3_commit_hook(D
35480 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65  ,C,P) and sqlite
35490 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
354a0 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73  D,C,P) functions
354b0 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50  .** return the P
354c0 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
354d0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
354e0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
354f0 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20  ction.** on the 
35500 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
35510 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
35520 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65   NULL for.** the
35530 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20   first call for 
35540 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e  each function on
35550 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f   D..**.** The co
35560 6d 6d 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63  mmit and rollbac
35570 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73  k hook callbacks
35580 20 61 72 65 20 6e 6f 74 20 72 65 65 6e 74 72 61   are not reentra
35590 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  nt..** The callb
355a0 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ack implementati
355b0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
355c0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
355d0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
355e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
355f0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
35600 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20   the callback.  
35610 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
35620 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
35630 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35640 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
35650 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
35660 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
35670 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
35680 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
35690 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
356a0 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c  commit.** or rol
356b0 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68  lback hook in th
356c0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
356d0 2a 20 4e 6f 74 65 20 74 68 61 74 20 72 75 6e 6e  * Note that runn
356e0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
356f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e  L statements, in
35700 63 6c 75 64 69 6e 67 20 53 45 4c 45 43 54 20 73  cluding SELECT s
35710 74 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72  tatements,.** or
35720 20 6d 65 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20   merely calling 
35730 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
35740 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
35750 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
35760 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
35770 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35780 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
35790 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
357a0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
357b0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74  h..**.** ^Regist
357c0 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
357d0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
357e0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
357f0 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d  ** ^When the com
35800 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  mit hook callbac
35810 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  k routine return
35820 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d  s zero, the [COM
35830 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  MIT].** operatio
35840 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20  n is allowed to 
35850 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c  continue normall
35860 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d  y.  ^If the comm
35870 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72  it hook.** retur
35880 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35890 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69  n the [COMMIT] i
358a0 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
358b0 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a   a [ROLLBACK]..*
358c0 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  * ^The rollback 
358d0 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  hook is invoked 
358e0 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68  on a rollback th
358f0 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  at results from 
35900 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b  a commit.** hook
35910 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a   returning non-z
35920 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20  ero, just as it 
35930 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e  would be with an
35940 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b  y other rollback
35950 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ..**.** ^For the
35960 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
35970 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
35980 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
35990 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c  have been.** rol
359a0 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65  led back if an e
359b0 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43  xplicit "ROLLBAC
359c0 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  K" statement is 
359d0 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20  executed, or.** 
359e0 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73  an error or cons
359f0 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e  traint causes an
35a00 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61   implicit rollba
35a10 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20  ck to occur..** 
35a20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61  ^The rollback ca
35a30 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
35a40 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
35a50 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74  action is.** aut
35a60 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
35a70 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74  d back because t
35a80 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
35a90 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
35aa0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
35ab0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70   the [sqlite3_up
35ac0 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74  date_hook()] int
35ad0 65 72 66 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54  erface..*/.SQLIT
35ae0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
35af0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
35b00 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
35b10 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
35b20 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
35b30 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   *sqlite3_rollba
35b40 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  ck_hook(sqlite3*
35b50 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a  , void(*)(void *
35b60 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
35b70 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
35b80 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61   Change Notifica
35b90 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
35ba0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35bb0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20  3_update_hook() 
35bc0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
35bd0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
35be0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
35bf0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35c00 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69  nnection] identi
35c10 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
35c20 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
35c30 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
35c40 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70  ever a row is up
35c50 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
35c60 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  or deleted..** ^
35c70 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
35c80 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
35c90 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63  all to this func
35ca0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20  tion.** for the 
35cb0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
35cc0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
35cd0 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ridden..**.** ^T
35ce0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
35cf0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
35d00 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  to the function 
35d10 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61  to invoke when a
35d20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74  .** row is updat
35d30 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
35d40 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  deleted..** ^The
35d50 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
35d60 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
35d70 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
35d80 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
35d90 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70  ** to sqlite3_up
35da0 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20  date_hook()..** 
35db0 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ^The second call
35dc0 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
35dd0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
35de0 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45  INSERT], [SQLITE
35df0 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20  _DELETE],.** or 
35e00 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c  [SQLITE_UPDATE],
35e10 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
35e20 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
35e30 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
35e40 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  back.** to be in
35e50 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74  voked..** ^The t
35e60 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
35e70 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
35e80 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
35e90 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  n pointers to th
35ea0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e  e.** database an
35eb0 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e  d table name con
35ec0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65  taining the affe
35ed0 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68  cted row..** ^Th
35ee0 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  e final callback
35ef0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
35f00 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
35f10 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65   row..** ^In the
35f20 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61   case of an upda
35f30 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  te, this is the 
35f40 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68  [rowid] after th
35f50 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70  e update takes p
35f60 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lace..**.** ^(Th
35f70 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73  e update hook is
35f80 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
35f90 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65  n internal syste
35fa0 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20  m tables are.** 
35fb0 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73  modified (i.e. s
35fc0 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64  qlite_master and
35fd0 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65   sqlite_sequence
35fe0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ).)^.**.** ^In t
35ff0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
36000 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75  mentation, the u
36010 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73  pdate hook.** is
36020 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
36030 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f  n duplication ro
36040 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62  ws are deleted b
36050 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20  ecause of an.** 
36060 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f  [ON CONFLICT | O
36070 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41  N CONFLICT REPLA
36080 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f  CE] clause.  ^No
36090 72 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20  r is the update 
360a0 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  hook.** invoked 
360b0 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65  when rows are de
360c0 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20  leted using the 
360d0 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
360e0 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20  zation]..** The 
360f0 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e  exceptions defin
36100 65 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  ed in this parag
36110 72 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67  raph might chang
36120 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
36130 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
36140 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70  te..**.** The up
36150 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d  date hook implem
36160 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  entation must no
36170 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
36180 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
36190 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
361a0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
361b0 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74  nvoked the updat
361c0 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74  e hook.  Any act
361d0 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
361e0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
361f0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
36200 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
36210 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
36220 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
36230 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
36240 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
36250 65 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20  ered the update 
36260 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  hook..** Note th
36270 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
36280 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
36290 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
362a0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
362b0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
362c0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
362d0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
362e0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
362f0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54  agraph..**.** ^T
36300 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  he sqlite3_updat
36310 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75  e_hook(D,C,P) fu
36320 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e  nction.** return
36330 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74  s the P argument
36340 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
36350 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68  us call.** on th
36360 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
36370 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
36380 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74  or NULL for.** t
36390 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e  he first call on
363a0 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c   D..**.** See al
363b0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
363c0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61  commit_hook()] a
363d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  nd [sqlite3_roll
363e0 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20  back_hook()].** 
363f0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 53  interfaces..*/.S
36400 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
36410 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
36420 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ook(.  sqlite3*,
36430 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
36440 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e   *,int ,char con
36450 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20  st *,char const 
36460 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
36470 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a  ,.  void*.);../*
36480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
36490 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
364a0 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63  Shared Pager Cac
364b0 68 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  he.** KEYWORDS: 
364c0 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a  {shared cache}.*
364d0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
364e0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
364f0 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72  isables the shar
36500 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
36510 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64  ase cache.** and
36520 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72   schema data str
36530 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20  uctures between 
36540 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36550 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f  tion | connectio
36560 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  ns].** to the sa
36570 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61  me database. Sha
36580 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
36590 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
365a0 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64  is true.** and d
365b0 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  isabled if the a
365c0 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65  rgument is false
365d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65  .)^.**.** ^Cache
365e0 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   sharing is enab
365f0 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64  led and disabled
36600 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70   for an entire p
36610 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20  rocess..** This 
36620 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f  is a change as o
36630 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
36640 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72   3.5.0. In prior
36650 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
36660 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20  ite,.** sharing 
36670 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
36680 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68  isabled for each
36690 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65   thread separate
366a0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
366b0 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  cache sharing mo
366c0 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69  de set by this i
366d0 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73  nterface effects
366e0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
366f0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ** calls to [sql
36700 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
36710 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
36720 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
36730 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78  open16()]..** Ex
36740 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  isting database 
36750 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74  connections cont
36760 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61  inue use the sha
36770 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61  ring mode.** tha
36780 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20  t was in effect 
36790 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79  at the time they
367a0 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a   were opened.)^.
367b0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
367c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
367d0 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
367e0 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
367f0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
36800 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
36810 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64  .  An [error cod
36820 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f  e] is returned o
36830 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a  therwise.)^.**.*
36840 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68 65 20  * ^Shared cache 
36850 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
36860 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73  efault. But this
36870 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
36880 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61  .** future relea
36890 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ses of SQLite.  
368a0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
368b0 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61  t care about sha
368c0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74  red.** cache set
368d0 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20  ting should set 
368e0 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a  it explicitly..*
368f0 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20  *.** See Also:  
36900 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43  [SQLite Shared-C
36910 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 53 51  ache Mode].*/.SQ
36920 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
36930 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
36940 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a  ed_cache(int);..
36950 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36960 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20  Attempt To Free 
36970 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a  Heap Memory.**.*
36980 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
36990 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
369a0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
369b0 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74  ts to free N byt
369c0 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65  es.** of heap me
369d0 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61  mory by dealloca
369e0 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  ting non-essenti
369f0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
36a00 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79  tions.** held by
36a10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69   the database li
36a20 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20  brary.   Memory 
36a30 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61  used to cache da
36a40 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20  tabase.** pages 
36a50 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  to improve perfo
36a60 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61  rmance is an exa
36a70 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65  mple of non-esse
36a80 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  ntial memory..**
36a90 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   ^sqlite3_releas
36aa0 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72  e_memory() retur
36ab0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
36ac0 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20   bytes actually 
36ad0 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20  freed,.** which 
36ae0 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72  might be more or
36af0 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61   less than the a
36b00 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e  mount requested.
36b10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36b20 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
36b30 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e  ) routine is a n
36b40 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a  o-op returning z
36b50 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  ero.** if SQLite
36b60 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64   is not compiled
36b70 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e   with [SQLITE_EN
36b80 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
36b90 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53  GEMENT]..**.** S
36ba0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
36bb0 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  3_db_release_mem
36bc0 6f 72 79 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  ory()].*/.SQLITE
36bd0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
36be0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
36bf0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
36c00 49 33 52 45 46 3a 20 46 72 65 65 20 4d 65 6d 6f  I3REF: Free Memo
36c10 72 79 20 55 73 65 64 20 42 79 20 41 20 44 61 74  ry Used By A Dat
36c20 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
36c30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36c40 74 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d  te3_db_release_m
36c50 65 6d 6f 72 79 28 44 29 20 69 6e 74 65 72 66 61  emory(D) interfa
36c60 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66  ce attempts to f
36c70 72 65 65 20 61 73 20 6d 75 63 68 20 68 65 61 70  ree as much heap
36c80 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 73 20 70 6f  .** memory as po
36c90 73 73 69 62 6c 65 20 66 72 6f 6d 20 64 61 74 61  ssible from data
36ca0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
36cb0 44 2e 20 55 6e 6c 69 6b 65 20 74 68 65 0a 2a 2a  D. Unlike the.**
36cc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
36cd0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 74 65  e_memory()] inte
36ce0 72 66 61 63 65 2c 20 74 68 69 73 20 69 6e 74 65  rface, this inte
36cf0 72 66 61 63 65 20 69 73 20 65 66 66 65 63 74 20  rface is effect 
36d00 65 76 65 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65  even.** when the
36d10 6e 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  n [SQLITE_ENABLE
36d20 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
36d30 4e 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  NT] compile-time
36d40 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 6d   option is.** om
36d50 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  itted..**.** See
36d60 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
36d70 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
36d80 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
36d90 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72  int sqlite3_db_r
36da0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 73 71  elease_memory(sq
36db0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
36dc0 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65  CAPI3REF: Impose
36dd0 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
36de0 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65   Size.**.** ^The
36df0 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
36e00 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e 74  ap_limit64() int
36e10 65 72 66 61 63 65 20 73 65 74 73 20 61 6e 64 2f  erface sets and/
36e20 6f 72 20 71 75 65 72 69 65 73 20 74 68 65 0a 2a  or queries the.*
36e30 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e 20  * soft limit on 
36e40 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65  the amount of he
36e50 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d  ap memory that m
36e60 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20  ay be allocated 
36e70 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53  by SQLite..** ^S
36e80 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f  QLite strives to
36e90 20 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f 72   keep heap memor
36ea0 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62 65  y utilization be
36eb0 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65 61  low the soft hea
36ec0 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72 65  p.** limit by re
36ed0 64 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62 65  ducing the numbe
36ee0 72 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64 20  r of pages held 
36ef0 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68  in the page cach
36f00 65 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65 6d  e.** as heap mem
36f10 6f 72 79 20 75 73 61 67 65 73 20 61 70 70 72 6f  ory usages appro
36f20 61 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74 2e  aches the limit.
36f30 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68 65  .** ^The soft he
36f40 61 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f 66  ap limit is "sof
36f50 74 22 20 62 65 63 61 75 73 65 20 65 76 65 6e 20  t" because even 
36f60 74 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73 74  though SQLite st
36f70 72 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a 2a  rives to stay.**
36f80 20 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69 74   below the limit
36f90 2c 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65 64  , it will exceed
36fa0 20 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68 65   the limit rathe
36fb0 72 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65 0a  r than generate.
36fc0 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  ** an [SQLITE_NO
36fd0 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e 20  MEM] error.  In 
36fe0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
36ff0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
37000 20 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72 79   .** is advisory
37010 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   only..**.** ^Th
37020 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
37030 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  rom sqlite3_soft
37040 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
37050 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  is the size of.*
37060 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  * the soft heap 
37070 6c 69 6d 69 74 20 70 72 69 6f 72 20 74 6f 20 74  limit prior to t
37080 68 65 20 63 61 6c 6c 2c 20 6f 72 20 6e 65 67 61  he call, or nega
37090 74 69 76 65 20 69 6e 20 74 68 65 20 63 61 73 65  tive in the case
370a0 20 6f 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e   of an.** error.
370b0 20 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65    ^If the argume
370c0 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  nt N is negative
370d0 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e  .** then no chan
370e0 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20 74 68  ge is made to th
370f0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37100 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  t.  Hence, the c
37110 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f  urrent.** size o
37120 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  f the soft heap 
37130 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64 65 74  limit can be det
37140 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b  ermined by invok
37150 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
37160 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
37170 28 29 20 77 69 74 68 20 61 20 6e 65 67 61 74 69  () with a negati
37180 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  ve argument..**.
37190 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d  ** ^If the argum
371a0 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20 74 68  ent N is zero th
371b0 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  en the soft heap
371c0 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61 62 6c   limit is disabl
371d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ed..**.** ^(The 
371e0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
371f0 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20  is not enforced 
37200 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  in the current i
37210 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
37220 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   if one or more 
37230 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  of following con
37240 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72 75 65  ditions are true
37250 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
37260 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20 68 65  <li> The soft he
37270 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20  ap limit is set 
37280 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e  to zero..** <li>
37290 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69   Memory accounti
372a0 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 20 75  ng is disabled u
372b0 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74 69  sing a combinati
372c0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  on of the.**    
372d0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69    [sqlite3_confi
372e0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
372f0 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e  G_MEMSTATUS],...
37300 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f 70 74  ) start-time opt
37310 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ion and.**      
37320 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  the [SQLITE_DEFA
37330 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  ULT_MEMSTATUS] c
37340 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
37350 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61  on..** <li> An a
37360 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 65 20  lternative page 
37370 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
37380 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66 69 65  tion is specifie
37390 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
373a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
373b0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
373c0 50 43 41 43 48 45 32 5d 2c 2e 2e 2e 29 2e 0a 2a  PCACHE2],...)..*
373d0 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65 20  * <li> The page 
373e0 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73 20  cache allocates 
373f0 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d  from its own mem
37400 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65  ory pool supplie
37410 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73 71  d.**      by [sq
37420 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
37430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
37440 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74  ECACHE],...) rat
37450 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
37460 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a   from the heap..
37470 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
37480 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20   Beginning with 
37490 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
374a0 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74 20 68  .7.3, the soft h
374b0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66  eap limit is enf
374c0 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c  orced.** regardl
374d0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
374e0 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
374f0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
37500 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63  MANAGEMENT].** c
37510 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
37520 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
37530 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41  With [SQLITE_ENA
37540 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
37550 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73  EMENT],.** the s
37560 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
37570 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76  s enforced on ev
37580 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
37590 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a  ation.  Without.
375a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
375b0 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
375c0 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74 20 68  ENT], the soft h
375d0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c  eap limit is onl
375e0 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68  y enforced.** wh
375f0 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c  en memory is all
37600 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 70 61  ocated by the pa
37610 67 65 20 63 61 63 68 65 2e 20 20 54 65 73 74 69  ge cache.  Testi
37620 6e 67 20 73 75 67 67 65 73 74 73 20 74 68 61 74  ng suggests that
37630 20 62 65 63 61 75 73 65 0a 2a 2a 20 74 68 65 20   because.** the 
37640 70 61 67 65 20 63 61 63 68 65 20 69 73 20 74 68  page cache is th
37650 65 20 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65  e predominate me
37660 6d 6f 72 79 20 75 73 65 72 20 69 6e 20 53 51 4c  mory user in SQL
37670 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70  ite, most.** app
37680 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61  lications will a
37690 63 68 69 65 76 65 20 61 64 65 71 75 61 74 65 20  chieve adequate 
376a0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
376b0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69 74 68  enforcement with
376c0 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  out.** the use o
376d0 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  f [SQLITE_ENABLE
376e0 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
376f0 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  NT]..**.** The c
37700 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75 6e 64  ircumstances und
37710 65 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 20  er which SQLite 
37720 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68 65  will enforce the
37730 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
37740 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20   may.** changes 
37750 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
37760 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
37770 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
37780 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
37790 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
377a0 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64(sqlite3_int6
377b0 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  4 N);../*.** CAP
377c0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
377d0 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d 69  d Soft Heap Limi
377e0 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44  t Interface.** D
377f0 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
37800 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65 63  This is a deprec
37810 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  ated version of 
37820 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  the [sqlite3_sof
37830 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
37840 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20  ].** interface. 
37850 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
37860 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68 69   provided for hi
37870 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
37880 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20  bility.** only. 
37890 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 61   All new applica
378a0 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 65  tions should use
378b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
378c0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
378d0 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  64()] interface 
378e0 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69 73  rather than this
378f0 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   one..*/.SQLITE_
37900 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
37910 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
37920 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
37930 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a  it(int N);.../*.
37940 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
37950 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62  ract Metadata Ab
37960 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20  out A Column Of 
37970 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54  A Table.**.** ^T
37980 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
37990 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f  rns metadata abo
379a0 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f  ut a specific co
379b0 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66  lumn of a specif
379c0 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74  ic.** database t
379d0 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20  able accessible 
379e0 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62  using the [datab
379f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37a00 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64  handle.** passed
37a10 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75   as the first fu
37a20 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
37a30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75  .**.** ^The colu
37a40 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  mn is identified
37a50 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20   by the second, 
37a60 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
37a70 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a   parameters to.*
37a80 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  * this function.
37a90 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
37aa0 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72  ameter is either
37ab0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
37ac0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e   database.** (i.
37ad0 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e. "main", "temp
37ae0 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65  ", or an attache
37af0 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74  d database) cont
37b00 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69  aining the speci
37b10 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72  fied.** table or
37b20 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73   NULL. ^If it is
37b30 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20   NULL, then all 
37b40 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
37b50 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a  es are searched.
37b60 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65  ** for the table
37b70 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
37b80 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62  algorithm used b
37b90 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  y the database e
37ba0 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f  ngine to.** reso
37bb0 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20  lve unqualified 
37bc0 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73  table references
37bd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
37be0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
37bf0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
37c00 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68   function are th
37c10 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  e table and colu
37c20 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  mn.** name of th
37c30 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e  e desired column
37c40 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
37c50 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65  Neither of these
37c60 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d   parameters.** m
37c70 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ay be NULL..**.*
37c80 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20 72  * ^Metadata is r
37c90 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69  eturned by writi
37ca0 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  ng to the memory
37cb0 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65   locations passe
37cc0 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20  d as the 5th.** 
37cd0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70  and subsequent p
37ce0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
37cf0 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79  s function. ^Any
37d00 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65   of these argume
37d10 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55  nts may be.** NU
37d20 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  LL, in which cas
37d30 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
37d40 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d  ing element of m
37d50 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74  etadata is omitt
37d60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f  ed..**.** ^(<blo
37d70 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
37d80 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
37d90 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d  * <tr><th> Param
37da0 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74  eter <th> Output
37db0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44  <br>Type <th>  D
37dc0 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a  escription.**.**
37dd0 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74   <tr><td> 5th <t
37de0 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c  d> const char* <
37df0 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a  td> Data type.**
37e00 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74   <tr><td> 6th <t
37e10 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c  d> const char* <
37e20 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61  td> Name of defa
37e30 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ult collation se
37e40 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74  quence.** <tr><t
37e50 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 7th <td> int 
37e60 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
37e70 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20  e if column has 
37e80 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74  a NOT NULL const
37e90 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  raint.** <tr><td
37ea0 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20  > 8th <td> int  
37eb0 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65         <td> True
37ec0 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61   if column is pa
37ed0 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52  rt of the PRIMAR
37ee0 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64  Y KEY.** <tr><td
37ef0 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20  > 9th <td> int  
37f00 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65         <td> True
37f10 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41   if column is [A
37f20 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a  UTOINCREMENT].**
37f30 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
37f40 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
37f50 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70  ** ^The memory p
37f60 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
37f70 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74   character point
37f80 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72  ers returned for
37f90 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74   the.** declarat
37fa0 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c  ion type and col
37fb0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
37fc0 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e  is valid only un
37fd0 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20  til the next.** 
37fe0 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69  call to any SQLi
37ff0 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e  te API function.
38000 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  .**.** ^If the s
38010 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69  pecified table i
38020 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65  s actually a vie
38030 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  w, an [error cod
38040 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
38050 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  **.** ^If the sp
38060 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69  ecified column i
38070 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22  s "rowid", "oid"
38080 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e   or "_rowid_" an
38090 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52  d an.** [INTEGER
380a0 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f   PRIMARY KEY] co
380b0 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78  lumn has been ex
380c0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
380d0 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  d, then the outp
380e0 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ut.** parameters
380f0 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65   are set for the
38100 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
38110 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49  ared column. ^(I
38120 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a  f there is no.**
38130 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
38140 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52  ared [INTEGER PR
38150 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d  IMARY KEY] colum
38160 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  n, then the outp
38170 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ut.** parameters
38180 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c   are set as foll
38190 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ows:.**.** <pre>
381a0 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70  .**     data typ
381b0 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20  e: "INTEGER".** 
381c0 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65      collation se
381d0 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22  quence: "BINARY"
381e0 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c  .**     not null
381f0 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61  : 0.**     prima
38200 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20  ry key: 1.**    
38210 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a   auto increment:
38220 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a   0.** </pre>)^.*
38230 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63  *.** ^(This func
38240 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e  tion may load on
38250 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61  e or more schema
38260 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20  s from database 
38270 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20  files. If an.** 
38280 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
38290 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73  ing this process
382a0 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75  , or if the requ
382b0 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63  ested table or c
382c0 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20  olumn.** cannot 
382d0 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72  be found, an [er
382e0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
382f0 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72  urned and an err
38300 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a  or message left.
38310 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62  ** in the [datab
38320 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
38330 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64  (to be retrieved
38340 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65   using sqlite3_e
38350 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a  rrmsg()).)^.**.*
38360 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73 20 6f  * ^This API is o
38370 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
38380 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
38390 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
383a0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
383b0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
383c0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
383d0 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
383e0 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ned..*/.SQLITE_A
383f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
38400 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61  able_column_meta
38410 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20  data(.  sqlite3 
38420 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
38430 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f      /* Connectio
38440 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  n handle */.  co
38450 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
38460 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74  e,        /* Dat
38470 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55  abase name or NU
38480 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  LL */.  const ch
38490 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20  ar *zTableName, 
384a0 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d      /* Table nam
384b0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
384c0 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20  r *zColumnName, 
384d0 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d     /* Column nam
384e0 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
384f0 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20  t **pzDataType, 
38500 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65     /* OUTPUT: De
38510 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65  clared data type
38520 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
38530 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20   **pzCollSeq,   
38540 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c    /* OUTPUT: Col
38550 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
38560 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  name */.  int *p
38570 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20  NotNull,        
38580 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
38590 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c   True if NOT NUL
385a0 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69  L constraint exi
385b0 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50  sts */.  int *pP
385c0 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20  rimaryKey,      
385d0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
385e0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70  True if column p
385f0 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69  art of PK */.  i
38600 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20  nt *pAutoinc    
38610 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
38620 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
38630 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63  lumn is auto-inc
38640 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  rement */.);../*
38650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
38660 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a  ad An Extension.
38670 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
38680 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53  rface loads an S
38690 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20  QLite extension 
386a0 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65  library from the
386b0 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a   named file..**.
386c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
386d0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
386e0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
386f0 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a  pts to load an.*
38700 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  * SQLite extensi
38710 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
38720 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
38730 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   zFile..**.** ^T
38740 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69  he entry point i
38750 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72  s zProc..** ^zPr
38760 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20  oc may be 0, in 
38770 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
38780 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79  ame of the entry
38790 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c   point.** defaul
387a0 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65  ts to "sqlite3_e
387b0 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74