System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 100c8b128aff679ba508e3f1c23e9fa661c08eff:


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 38 22 0a 23 64 65 66 69 6e 65 20 53 51  .7.8".#define SQ
1030: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1040: 42 45 52 20 33 30 30 37 30 30 38 0a 23 64 65 66  BER 3007008.#def
1050: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1060: 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 31 2d  E_ID      "2011-
1070: 30 38 2d 33 31 20 32 33 3a 35 37 3a 32 32 20 32  08-31 23:57:22 2
1080: 38 36 39 65 64 32 38 32 39 39 62 31 63 39 66 33  869ed28299b1c9f3
1090: 35 35 65 63 63 32 34 36 33 35 38 33 30 66 37 66  55ecc24635830f7f
10a0: 31 32 34 39 31 32 36 22 0a 0a 2f 2a 0a 2a 2a 20  1249126"../*.** 
10b0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
10c0: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
10d0: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45  on Numbers.** KE
10e0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
10f0: 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33  version, sqlite3
1100: 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20  _sourceid.**.** 
1110: 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  These interfaces
1120: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d   provide the sam
1130: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  e information as
1140: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52   the [SQLITE_VER
1150: 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  SION],.** [SQLIT
1160: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1170: 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53  ], and [SQLITE_S
1180: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
1190: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a  rocessor macros.
11a0: 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63  ** but are assoc
11b0: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c  iated with the l
11c0: 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f  ibrary instead o
11d0: 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  f the header fil
11e0: 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a  e.  ^(Cautious.*
11f0: 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  * programmers mi
1200: 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65  ght include asse
1210: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20  rt() statements 
1220: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
1230: 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66  tion to.** verif
1240: 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65  y that values re
1250: 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1260: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68  interfaces match
1270: 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a   the macros in.*
1280: 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e  * the header, an
1290: 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68  d thus insure th
12a0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
12b0: 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  on is.** compile
12c0: 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20  d with matching 
12d0: 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64  library and head
12e0: 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  er files..**.** 
12f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1300: 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c  >.** assert( sql
1310: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1320: 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45  number()==SQLITE
1330: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
1340: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1350: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75  rcmp(sqlite3_sou
1360: 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53  rceid(),SQLITE_S
1370: 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a  OURCE_ID)==0 );.
1380: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
1390: 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  p(sqlite3_libver
13a0: 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45  sion(),SQLITE_VE
13b0: 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20  RSION)==0 );.** 
13c0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13d0: 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
13e0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
13f0: 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  [] string consta
1400: 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  nt contains the 
1410: 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f  text of [SQLITE_
1420: 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72  VERSION].** macr
1430: 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  o.  ^The sqlite3
1440: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75  _libversion() fu
1450: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1460: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
1470: 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  ** to the sqlite
1480: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
1490: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
14a0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
14b0: 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69  sion().** functi
14c0: 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  on is provided f
14d0: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73  or use in DLLs s
14e0: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75  ince DLL users u
14f0: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61  sually do not ha
1500: 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63  ve.** direct acc
1510: 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f  ess to string co
1520: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74  nstants within t
1530: 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a  he DLL.  ^The.**
1540: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1550: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e  ion_number() fun
1560: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e  ction returns an
1570: 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74   integer equal t
1580: 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  o.** [SQLITE_VER
1590: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e  SION_NUMBER].  ^
15a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  The sqlite3_sour
15b0: 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  ceid() function 
15c0: 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f  returns .** a po
15d0: 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e  inter to a strin
15e0: 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65  g constant whose
15f0: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61   value is the sa
1600: 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53  me as the .** [S
1610: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d  QLITE_SOURCE_ID]
1620: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1630: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  macro..**.** See
1640: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76   also: [sqlite_v
1650: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1660: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1670: 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1680: 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  I SQLITE_EXTERN 
1690: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
16a0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51  e3_version[];.SQ
16b0: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
16c0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
16d0: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53  version(void);.S
16e0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16f0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1700: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51  urceid(void);.SQ
1710: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1720: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1730: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1740: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1750: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1760: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69  Compilation Opti
1770: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a  ons Diagnostics.
1780: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1790: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
17a0: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e  _used() function
17b0: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20   returns 0 or 1 
17c0: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77  .** indicating w
17d0: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69  hether the speci
17e0: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20  fied option was 
17f0: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63  defined at .** c
1800: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54  ompile time.  ^T
1810: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69  he SQLITE_ prefi
1820: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  x may be omitted
1830: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70   from the .** op
1840: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64  tion name passed
1850: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
1860: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1870: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .  .**.** ^The s
1880: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1890: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74  tion_get() funct
18a0: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61  ion allows itera
18b0: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65  ting.** over the
18c0: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73   list of options
18d0: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e   that were defin
18e0: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  ed at compile ti
18f0: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69  me by.** returni
1900: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70  ng the N-th comp
1910: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile time option 
1920: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69  string.  ^If N i
1930: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a  s out of range,.
1940: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
1950: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72  leoption_get() r
1960: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1970: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c  inter.  ^The SQL
1980: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20  ITE_ .** prefix 
1990: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
19a0: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75  any strings retu
19b0: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  rned by .** sqli
19c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19d0: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  n_get()..**.** ^
19e0: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20  Support for the 
19f0: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74  diagnostic funct
1a00: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ions sqlite3_com
1a10: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a20: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ).** and sqlite3
1a30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a40: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74  et() may be omit
1a50: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e  ted by specifyin
1a60: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  g the .** [SQLIT
1a70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1a80: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69  TION_DIAGS] opti
1a90: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  on at compile ti
1aa0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  me..**.** See al
1ab0: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  so: SQL function
1ac0: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  s [sqlite_compil
1ad0: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20  eoption_used()] 
1ae0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63  and.** [sqlite_c
1af0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b00: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d  ()] and the [com
1b10: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61  pile_options pra
1b20: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  gma]..*/.#ifndef
1b30: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
1b40: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
1b50: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1b60: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1b70: 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74  ption_used(const
1b80: 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29   char *zOptName)
1b90: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
1ba0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1bb0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1bc0: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
1bd0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1be0: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
1bf0: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
1c00: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
1c10: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1c20: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
1c30: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
1c40: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
1c50: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
1c60: 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69 6e 67  ompiled mutexing
1c70: 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 75   code omitted du
1c80: 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  e to the.** [SQL
1c90: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1ca0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
1cb0: 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74 6f  ion being set to
1cc0: 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65   0..**.** SQLite
1cd0: 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64   can be compiled
1ce0: 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74   with or without
1cf0: 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a   mutexes.  When.
1d00: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
1d10: 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 65  HREADSAFE] C pre
1d20: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
1d30: 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78  is 1 or 2, mutex
1d40: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
1d50: 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20  d and SQLite is 
1d60: 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 65  threadsafe.  Whe
1d70: 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  n the.** [SQLITE
1d80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
1d90: 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65  ro is 0, .** the
1da0: 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69   mutexes are omi
1db0: 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74  tted.  Without t
1dc0: 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69  he mutexes, it i
1dd0: 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f  s not safe.** to
1de0: 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63   use SQLite conc
1df0: 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f  urrently from mo
1e00: 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65  re than one thre
1e10: 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69  ad..**.** Enabli
1e20: 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72  ng mutexes incur
1e30: 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70  s a measurable p
1e40: 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c  erformance penal
1e50: 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65  ty..** So if spe
1e60: 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20  ed is of utmost 
1e70: 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d  importance, it m
1e80: 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69  akes sense to di
1e90: 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74  sable.** the mut
1ea0: 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d  exes.  But for m
1eb0: 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d  aximum safety, m
1ec0: 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65  utexes should be
1ed0: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68   enabled..** ^Th
1ee0: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
1ef0: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65  or is for mutexe
1f00: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e  s to be enabled.
1f10: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f20: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1f30: 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74  d by an applicat
1f40: 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ion to make sure
1f50: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72   that the.** ver
1f60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74  sion of SQLite t
1f70: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e  hat it is linkin
1f80: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f  g against was co
1f90: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
1fa0: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69  he desired setti
1fb0: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ng of the [SQLIT
1fc0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fd0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cro..**.** This 
1fe0: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
1ff0: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f  eports on the co
2000: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78  mpile-time mutex
2010: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74   setting.** of t
2020: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
2030: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66  DSAFE] flag.  If
2040: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
2050: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49  led with.** SQLI
2060: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20  TE_THREADSAFE=1 
2070: 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 78  or =2 then mutex
2080: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  es are enabled b
2090: 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a  y default but.**
20a0: 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72   can be fully or
20b0: 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62   partially disab
20c0: 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c  led using a call
20d0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
20e0: 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74  fig()].** with t
20f0: 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45  he verbs [SQLITE
2100: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
2110: 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  READ], [SQLITE_C
2120: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
2130: 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  D],.** or [SQLIT
2140: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e  E_CONFIG_MUTEX].
2150: 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76    ^(The return v
2160: 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73  alue of the.** s
2170: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2180: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  e() function sho
2190: 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70  ws only the comp
21a0: 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67  ile-time setting
21b0: 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61   of.** thread sa
21c0: 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75  fety, not any ru
21d0: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74  n-time changes t
21e0: 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d  o that setting m
21f0: 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65  ade by.** sqlite
2200: 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f  3_config(). In o
2210: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
2220: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
2230: 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  m sqlite3_thread
2240: 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63  safe().** is unc
2250: 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20  hanged by calls 
2260: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
2270: 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  g().)^.**.** See
2280: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
2290: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74  mode] documentat
22a0: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
22b0: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
22c0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
22d0: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
22e0: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
22f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
2300: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2310: 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f   Handle.** KEYWO
2320: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63  RDS: {database c
2330: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61  onnection} {data
2340: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2350: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  }.**.** Each ope
2360: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
2370: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
2380: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   by a pointer to
2390: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a   an instance of.
23a0: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74  ** the opaque st
23b0: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
23c0: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
23d0: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
23e0: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
23f0: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
2400: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
2410: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
2420: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2430: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2440: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
2450: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
2460: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e  constructors, an
2470: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2480: 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65  ()].** is its de
2490: 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65  structor.  There
24a0: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20   are many other 
24b0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
24c0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
24d0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
24e0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
24f0: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
2500: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
2510: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
2520: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2530: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2540: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2550: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2560: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2570: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2580: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
2590: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
25a0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
25b0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
25c0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
25d0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
25e0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
25f0: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
2600: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
2610: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
2620: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2630: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2640: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2650: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2660: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2670: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2680: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
2690: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
26a0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
26b0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
26c0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
26d0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
26e0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
26f0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2700: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
2710: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
2720: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2730: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2740: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2750: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2760: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2770: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2780: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
2790: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
27a0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
27b0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
27c0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
27d0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
27e0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
27f0: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2800: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2810: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2820: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2830: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2840: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2850: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2860: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49  ef unsigned SQLI
2870: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f  if defined(_MSC_
28a0: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28  VER) || defined(
28b0: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20  __BORLANDC__).  
28c0: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20  typedef __int64 
28d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
28e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
28f0: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
2900: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20  uint64;.#else.  
2910: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e  typedef long lon
2920: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74  g int sqlite_int
2930: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2940: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67  signed long long
2950: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74   int sqlite_uint
2960: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64  64;.#endif.typed
2970: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  ef sqlite_int64 
2980: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74  sqlite3_int64;.t
2990: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69  ypedef sqlite_ui
29a0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e  nt64 sqlite3_uin
29b0: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63  t64;../*.** If c
29c0: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70  ompiling for a p
29d0: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61  rocessor that la
29e0: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  cks floating poi
29f0: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73  nt support,.** s
2a00: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65  ubstitute intege
2a10: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70  r for floating-p
2a20: 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  oint..*/.#ifdef 
2a30: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
2a40: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66  TING_POINT.# def
2a50: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  ine double sqlit
2a60: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a  e3_int64.#endif.
2a70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a80: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62   Closing A Datab
2a90: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
2aa0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ab0: 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69 6e  3_close() routin
2ac0: 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75 63  e is the destruc
2ad0: 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  tor for the [sql
2ae0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ite3] object..**
2af0: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
2b00: 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75 72  e3_close() retur
2b10: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 74  n SQLITE_OK if t
2b20: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2b30: 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65 73  ect is.** succes
2b40: 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64  sfully destroyed
2b50: 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61   and all associa
2b60: 74 65 64 20 72 65 73 6f 75 72 63 65 73 20 61 72  ted resources ar
2b70: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a  e deallocated..*
2b80: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
2b90: 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65 33 5f  s must [sqlite3_
2ba0: 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
2bb0: 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72  ize] all [prepar
2bc0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a  ed statements].*
2bd0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  * and [sqlite3_b
2be0: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73  lob_close | clos
2bf0: 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e  e] all [BLOB han
2c00: 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65 64  dles] associated
2c10: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73 71   with.** the [sq
2c20: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2c30: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2c40: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2c50: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2c60: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69  qlite3_close() i
2c70: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
2c80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c90: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
2ca0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
2cb0: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
2cc0: 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c 4f 42  ements] or [BLOB
2cd0: 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65 6e 20   handles], then 
2ce0: 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  it returns.** SQ
2cf0: 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a 2a 2a  LITE_BUSY..**.**
2d00: 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f 63 6c   ^If [sqlite3_cl
2d10: 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ose()] is invoke
2d20: 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61  d while a transa
2d30: 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a  ction is open,.*
2d40: 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  * the transactio
2d50: 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  n is automatical
2d60: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
2d70: 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61  **.** The C para
2d80: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2d90: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 73 74  3_close(C)] must
2da0: 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c   be either a NUL
2db0: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20  L.** pointer or 
2dc0: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
2dd0: 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61  ect pointer obta
2de0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
2df0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2e00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2e10: 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
2e20: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
2e30: 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79  d not previously
2e40: 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c   closed..** ^Cal
2e50: 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f  ling sqlite3_clo
2e60: 73 65 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  se() with a NULL
2e70: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
2e80: 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72 6d 6c  t is a .** harml
2e90: 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51  ess no-op..*/.SQ
2ea0: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2eb0: 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74  ite3_close(sqlit
2ec0: 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  e3 *);../*.** Th
2ed0: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
2ee0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
2ef0: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
2f00: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
2f10: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
2f20: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
2f30: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
2f40: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
2f50: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
2f60: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
2f70: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
2f80: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
2f90: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
2fa0: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
2fb0: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
2fc0: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a   Interface.**.**
2fd0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
2fe0: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
2ff0: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3000: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3010: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3020: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3030: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
3040: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3050: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
3060: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
3070: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
3080: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
3090: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
30a0: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
30b0: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
30c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30d0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
30e0: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
30f0: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3100: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3110: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3120: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3130: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
3140: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
3150: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
3160: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
3170: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
3180: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
3190: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
31a0: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
31b0: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
31c0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
31d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
31e0: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
31f0: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3200: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3210: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3220: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3230: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
3240: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
3250: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3260: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
3270: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
3280: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
3290: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
32a0: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
32b0: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
32c0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
32d0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
32e0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
32f0: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3300: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3310: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3320: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3330: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
3340: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
3350: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
3360: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3370: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3380: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
3390: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
33a0: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
33b0: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
33c0: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
33d0: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
33e0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
33f0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3400: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3410: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3420: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3430: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
3440: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
3450: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
3460: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
3470: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
3480: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3490: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
34a0: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
34b0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
34c0: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
34d0: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
34e0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
34f0: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3500: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3510: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3520: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3530: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
3540: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3550: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
3560: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
3570: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3580: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3590: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
35a0: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
35b0: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
35c0: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
35d0: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
35e0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
35f0: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3600: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3610: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
3620: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3630: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3640: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3650: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3660: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3670: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3680: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3690: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
36a0: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
36b0: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
36c0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
36d0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
36e0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36f0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3700: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3710: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
3720: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
3730: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3740: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3750: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3760: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3770: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3780: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3790: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
37a0: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
37b0: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
37c0: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
37d0: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
37e0: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
37f0: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3800: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3810: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
3820: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
3830: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3840: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3850: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3860: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3870: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3880: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3890: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
38a0: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
38b0: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
38c0: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
38d0: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
38e0: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
38f0: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3900: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3910: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
3920: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
3930: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3940: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3950: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3960: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3970: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3980: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3990: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
39a0: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
39b0: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
39c0: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
39d0: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
39e0: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
39f0: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
3a00: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
3a10: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
3a20: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
3a30: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
3a40: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3a50: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
3a60: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
3a70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3a80: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3a90: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3aa0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3ab0: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3ac0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3ad0: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
3ae0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3af0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3b00: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3b10: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3b20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3b30: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3b40: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3b50: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3b60: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3b70: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3b80: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3b90: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3ba0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3bb0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3bc0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3bd0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3be0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
3bf0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
3c00: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
3c10: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
3c20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3c40: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
3c50: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
3c60: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
3c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c80: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
3c90: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
3ca0: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
3cb0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
3cc0: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
3cd0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
3ce0: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
3cf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3d10: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
3d20: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
3d30: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
3d40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d50: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
3d60: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
3d70: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
3d80: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
3d90: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
3da0: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
3db0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
3dc0: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
3dd0: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
3de0: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
3df0: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
3e00: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
3e10: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
3e20: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
3e30: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
3e40: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
3e50: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73  r to indicates s
3e60: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
3e70: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
3e80: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
3e90: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
3ea0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3eb0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
3ec0: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
3ed0: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
3ee0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c  d result codes],
3ef0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  .** [sqlite3_vta
3f00: 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
3f10: 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
3f20: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
3f30: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
3f40: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3f50: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3f60: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3f70: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
3f80: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
3f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
3fa0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
3fb0: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
3fc0: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
3fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fe0: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
3ff0: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
4000: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
4010: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
4020: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
4030: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
4040: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
4050: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4060: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
4070: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
4080: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
4090: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
40a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
40b0: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
40c0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
40d0: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
40e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40f0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
4100: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
4110: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
4120: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4130: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
4140: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
4150: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
4160: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4170: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
4180: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
4190: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
41a0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
41b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
41c0: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
41d0: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
41e0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
41f0: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
4200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4210: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
4220: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
4230: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
4240: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
4250: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
4260: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
4270: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
4280: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
4290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42a0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
42b0: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
42c0: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
42d0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
42e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
42f0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4300: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4310: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4320: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
4330: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4340: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
4350: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
4360: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
4370: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
4380: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
4390: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
43a0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
43b0: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
43d0: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
43e0: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
43f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4400: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
4410: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
4420: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
4430: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4440: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
4450: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
4460: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
4470: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
4480: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
4490: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
44a0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
44b0: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
44c0: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
44d0: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
44e0: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
44f0: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
4500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4510: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
4520: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
4530: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
4540: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
4550: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
4560: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
4570: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
4580: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
4590: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
45a0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
45b0: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
45c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
45d0: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
45e0: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
45f0: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
4600: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
4610: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
4620: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
4630: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4640: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
4650: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
4660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
4670: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
4680: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
4690: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
46a0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
46b0: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
46c0: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
46d0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
46e0: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
46f0: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4700: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4710: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4720: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4730: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4740: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
4750: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
4760: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
4770: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
4780: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
4790: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
47a0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
47b0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
47c0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
47d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
47e0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
47f0: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4800: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4810: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4820: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4830: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4840: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
4850: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
4860: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
4870: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
4880: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
4890: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
48a0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
48b0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
48c0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
48d0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
48e0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
48f0: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4900: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4910: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4920: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4930: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4940: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4950: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
4960: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
4970: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
4980: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
4990: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
49a0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
49b0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
49c0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
49d0: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
49e0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49f0: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4a00: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4a10: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4a20: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4a30: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4a40: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4a50: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
4a60: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
4a70: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
4a80: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4a90: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
4aa0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
4ab0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
4ac0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
4ad0: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
4ae0: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
4af0: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
4b00: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
4b10: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4b20: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
4b30: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
4b40: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
4b50: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
4b60: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
4b70: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
4b80: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
4b90: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
4ba0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
4bb0: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
4bc0: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
4bd0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
4be0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4bf0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
4c00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4c10: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4c20: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4c30: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
4c40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4c50: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
4c60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4c70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4c80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4c90: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4ca0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4cb0: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
4cc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4cd0: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
4ce0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4cf0: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
4d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d10: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4d20: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4d30: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
4d40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4d50: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
4d60: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4d70: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4d90: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
4da0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4db0: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
4dc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4dd0: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
4de0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4df0: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
4e00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e10: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
4e20: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e30: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
4e40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e50: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
4e60: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e70: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4e80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e90: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4ea0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4eb0: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
4ec0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ed0: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
4ee0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ef0: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
4f00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f10: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
4f20: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
4f30: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
4f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f50: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
4f60: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f70: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
4f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f90: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4fa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fb0: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
4fc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fd0: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
4fe0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ff0: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
5000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5010: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
5020: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5030: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
5040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5050: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
5060: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5070: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
5080: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5090: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
50a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
50b0: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
50c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
50d0: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
50e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
50f0: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
5100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5110: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
5120: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5130: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
5140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5150: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
5160: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
5170: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
5180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5190: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
51a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
51b0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
51c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
51d0: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
51e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
51f0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5210: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5220: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5230: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5240: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5250: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
5260: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
5270: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
5280: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5290: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
52a0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
52b0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
52c0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
52d0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
52e0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
52f0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
5300: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
5310: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5320: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5330: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5340: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5350: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
5360: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
5370: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5380: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
5390: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
53a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53b0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
53c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
53d0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
53e0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
53f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5400: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5410: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5420: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5430: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5450: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5460: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5470: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5480: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5490: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54a0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
54b0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
54c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
54d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54e0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
54f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5500: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5520: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5530: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5540: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5550: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5560: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
5570: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5580: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5590: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
55a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55b0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
55c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
55d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
55e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55f0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5600: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5610: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5620: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5630: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5640: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5650: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5670: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5680: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5690: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
56a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56b0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
56c0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
56d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
56e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56f0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5700: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5710: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5730: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5740: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
5750: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5770: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
5780: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
5790: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
57a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
57b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57c0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
57d0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
57e0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
57f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5810: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
5820: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
5830: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5840: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5860: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
5870: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
5880: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5890: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
58a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58b0: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
58c0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
58d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
58e0: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
58f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5900: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
5910: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
5920: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5930: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
5940: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
5950: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
5960: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
5970: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5980: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
5990: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
59a0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
59b0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
59c0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
59d0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
59e0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
59f0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5a00: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5a10: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5a20: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5a30: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5a40: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
5a50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5a60: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
5a70: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
5a80: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
5a90: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
5aa0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5ab0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
5ac0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
5ad0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
5ae0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
5af0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
5b00: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
5b10: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
5b20: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
5b30: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
5b40: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
5b50: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5b60: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
5b70: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
5b80: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
5b90: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
5ba0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
5bb0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
5bc0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
5bd0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
5be0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
5bf0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
5c00: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
5c10: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5c20: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
5c30: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
5c40: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
5c50: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
5c60: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
5c70: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
5c80: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  e()..*/.#define 
5c90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5ca0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
5cb0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
5cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5cd0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
5ce0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5cf0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5d00: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5d10: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
5d20: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
5d30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5d40: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
5d50: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5d60: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
5d70: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
5d80: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
5d90: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5da0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5db0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5dc0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5dd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5de0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
5df0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5e00: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
5e10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5e20: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
5e30: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5e50: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
5e60: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5e70: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
5e80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5e90: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
5ea0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
5eb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5ec0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
5ed0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ee0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
5ef0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
5f00: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
5f10: 20 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a   0x00000800../*.
5f20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
5f30: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
5f40: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
5f50: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
5f60: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
5f70: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
5f80: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
5f90: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
5fa0: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
5fb0: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
5fc0: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
5fd0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
5fe0: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
5ff0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
6000: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
6010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6020: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
6030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6040: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
6050: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
6060: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
6070: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
6080: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
6090: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
60a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
60b0: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
60c0: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
60d0: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
60e0: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
60f0: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
6100: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6110: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
6120: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
6130: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
6140: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6150: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
6160: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
6170: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
6180: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
6190: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
61a0: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
61b0: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
61c0: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
61d0: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
61e0: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
61f0: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
6200: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
6210: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6220: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
6230: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
6240: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
6250: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
6260: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
6270: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
6280: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
6290: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
62a0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
62b0: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
62c0: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
62d0: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
62e0: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
62f0: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
6300: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
6310: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6320: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6330: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
6340: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
6350: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
6360: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
6370: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
6380: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
6390: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
63a0: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
63b0: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
63c0: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
63d0: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
63e0: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
63f0: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
6400: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
6410: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
6420: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
6430: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
6440: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
6450: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
6460: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
6470: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
6480: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
6490: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
64a0: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
64b0: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
64c0: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
64d0: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
64e0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
64f0: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
6500: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
6510: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
6520: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6530: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6540: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
6550: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
6560: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
6570: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
6580: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
6590: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
65a0: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
65b0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
65c0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
65d0: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
65e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
65f0: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
6600: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
6610: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6620: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
6630: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
6640: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
6650: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
6660: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
6670: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
6680: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
6690: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
66a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
66b0: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
66c0: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
66d0: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
66e0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
66f0: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
6700: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
6710: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
6720: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
6730: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
6740: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
6750: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
6760: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
6770: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6780: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6790: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
67a0: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
67b0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
67c0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
67d0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
67e0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
67f0: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
6800: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
6810: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
6820: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
6830: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
6840: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
6850: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
6860: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
6870: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6880: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
6890: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
68a0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
68b0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
68c0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
68d0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
68e0: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
68f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
6900: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
6910: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
6920: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
6930: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6940: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
6950: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
6960: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
6970: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
6980: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
6990: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
69a0: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
69b0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
69c0: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
69d0: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
69e0: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
69f0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
6a00: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
6a10: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6a20: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
6a30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
6a40: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
6a50: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
6a60: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
6a70: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
6a80: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
6a90: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
6aa0: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
6ab0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
6ac0: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
6ad0: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6ae0: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6af0: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6b00: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6b10: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
6b20: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
6b30: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
6b40: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
6b50: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
6b60: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
6b70: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
6b80: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
6b90: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
6ba0: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
6bb0: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
6bc0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
6bd0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
6be0: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
6bf0: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
6c00: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
6c10: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
6c20: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
6c30: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
6c40: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
6c50: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
6c60: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
6c70: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
6c80: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
6c90: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
6ca0: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
6cb0: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
6cc0: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
6cd0: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
6ce0: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
6cf0: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
6d00: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
6d10: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6d20: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
6d30: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6d40: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
6d50: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
6d60: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
6d70: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
6d80: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
6d90: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6da0: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
6db0: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
6dc0: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
6dd0: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
6de0: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
6df0: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
6e00: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
6e10: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
6e20: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
6e30: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
6e40: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
6e50: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
6e60: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
6e70: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
6e80: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
6e90: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
6ea0: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
6eb0: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
6ec0: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
6ed0: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
6ee0: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
6ef0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
6f00: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
6f10: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
6f20: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
6f30: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
6f40: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
6f50: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
6f60: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
6f70: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
6f80: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
6f90: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
6fa0: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
6fb0: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
6fc0: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
6fd0: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
6fe0: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
6ff0: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
7000: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
7010: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
7020: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
7030: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
7040: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
7050: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
7060: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
7070: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
7080: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
7090: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
70a0: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
70b0: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
70c0: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
70d0: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
70e0: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
70f0: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
7100: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
7110: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
7120: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
7130: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
7140: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
7150: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
7160: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
7170: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
7180: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
7190: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
71a0: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43  .** A [SQLITE_FC
71b0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20  NTL_LOCKSTATE | 
71c0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
71d0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
71e0: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
71f0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7200: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7210: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7220: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7230: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7240: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7250: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7260: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
7270: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
7280: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
7290: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
72a0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
72b0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
72c0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
72d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
72e0: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
72f0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
7300: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
7310: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
7320: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
7330: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
7340: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
7350: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
7360: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
7370: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
7380: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
7390: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
73a0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
73b0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
73c0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
73d0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
73e0: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
73f0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
7400: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
7410: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
7420: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7430: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
7440: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7450: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
7460: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7470: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
7480: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7490: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
74a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
74b0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
74c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
74d0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
74e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
74f0: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
7500: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7510: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
7520: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7530: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
7540: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7550: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
7560: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7570: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
7580: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
7590: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
75a0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
75b0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
75c0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
75d0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
75e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
75f0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
7600: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
7610: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
7620: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
7630: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
7640: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
7650: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
7660: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
7670: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
7680: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
7690: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
76a0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
76b0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
76c0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
76d0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
76e0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
76f0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
7700: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
7710: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
7720: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
7730: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
7740: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
7750: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7760: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
7770: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
7780: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
7790: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
77a0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
77b0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
77c0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
77d0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
77e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
77f0: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
7800: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
7810: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
7820: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
7830: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
7840: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
7850: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
7860: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
7870: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
7880: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
7890: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
78a0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
78b0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
78c0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
78d0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
78e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
78f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7900: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
7910: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
7920: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7930: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
7940: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
7950: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7960: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
7970: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7980: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
7990: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
79a0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
79b0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
79c0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
79d0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
79e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
79f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
7a00: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
7a10: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
7a20: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
7a30: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
7a40: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
7a50: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
7a60: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
7a70: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7a80: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
7a90: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
7aa0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
7ab0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
7ac0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
7ad0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
7ae0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
7af0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
7b00: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
7b10: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
7b20: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
7b30: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
7b40: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
7b50: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
7b60: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7b70: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
7b80: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
7b90: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7ba0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
7bb0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
7bc0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
7bd0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
7be0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7bf0: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
7c00: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
7c10: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
7c20: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
7c30: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
7c40: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
7c50: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
7c60: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
7c70: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7c80: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
7c90: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7ca0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
7cb0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7cc0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
7cd0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
7ce0: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
7cf0: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
7d00: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
7d10: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
7d20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
7d30: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
7d40: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a  trol Opcodes.**.
7d50: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
7d60: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f   constants are o
7d70: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78  pcodes for the x
7d80: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7d90: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  od.** of the [sq
7da0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7db0: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72  ] object and for
7dc0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7dd0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a  le_control()].**
7de0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
7df0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
7e00: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f  NTL_LOCKSTATE] o
7e10: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
7e20: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
7e30: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
7e40: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
7e50: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77  trol method to w
7e60: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74  rite the current
7e70: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65   state of.** the
7e80: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53   lock (one of [S
7e90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
7ea0: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  , [SQLITE_LOCK_S
7eb0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  HARED],.** [SQLI
7ec0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7ed0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7ee0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51  PENDING], or [SQ
7ef0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7f00: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e  IVE]).** into an
7f10: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68   integer that th
7f20: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
7f30: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20  points to. This 
7f40: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
7f50: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
7f60: 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  ting and only ne
7f70: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
7f80: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
7f90: 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e  TEST.** is defin
7fa0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ed..**.** The [S
7fb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
7fc0: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
7fd0: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
7fe0: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
7ff0: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
8000: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
8010: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
8020: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
8030: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
8040: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
8050: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
8060: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
8070: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
8080: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
8090: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
80a0: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
80b0: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
80c0: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
80d0: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
80e0: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
80f0: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
8100: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
8110: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
8120: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
8130: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8140: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
8150: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8160: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
8170: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
8180: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
8190: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
81a0: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
81b0: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
81c0: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
81d0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
81e0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
81f0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8200: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
8210: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
8220: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
8230: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
8240: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
8250: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
8260: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
8270: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
8280: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
8290: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
82a0: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
82b0: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
82c0: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
82d0: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
82e0: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
82f0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
8300: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ystems..**.** Th
8310: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8320: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  FILE_POINTER] op
8330: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
8340: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
8350: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
8360: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
8370: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
8380: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
8390: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
83a0: 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b  tion.  See the [
83b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
83c0: 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74  trol()] document
83d0: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64  ation for.** add
83e0: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
83f0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ion..**.** ^(The
8400: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8410: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63  YNC_OMITTED] opc
8420: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
8430: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a   internally by.*
8440: 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e  * SQLite and sen
8450: 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69  t to all VFSes i
8460: 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c  n place of a cal
8470: 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d  l to the xSync m
8480: 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68  ethod.** when th
8490: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
84a0: 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d  ction has [PRAGM
84b0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73  A synchronous] s
84c0: 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20  et to OFF.)^.** 
84d0: 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64  Some specialized
84e0: 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73   VFSes need this
84f0: 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72   signal in order
8500: 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72   to operate corr
8510: 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50  ectly.** when [P
8520: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
8530: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
8540: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73  ronous=OFF] is s
8550: 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a  et, but most .**
8560: 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65   VFSes do not ne
8570: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61  ed this signal a
8580: 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  nd should silent
8590: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
85a0: 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  pcode..** Applic
85b0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
85c0: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
85d0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
85e0: 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63  with this.** opc
85f0: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
8600: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
8610: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
8620: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
8630: 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65  es.** that do re
8640: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
8650: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
8660: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
8670: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
8680: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
8690: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
86a0: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
86b0: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
86c0: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
86d0: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
86e0: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
86f0: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f  ] in order to wo
8700: 72 6b 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  rk to provide ro
8710: 62 75 73 74 6e 65 73 73 20 61 67 61 69 6e 73 74  bustness against
8720: 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70  .** anti-virus p
8730: 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66  rograms.  By def
8740: 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77  ault, the window
8750: 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79  s VFS will retry
8760: 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66   file read,.** f
8770: 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66  ile write, and f
8780: 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 74  ile delete opert
8790: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
87a0: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
87b0: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
87c0: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
87d0: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
87e0: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
87f0: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
8800: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
8810: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
8820: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
8830: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
8840: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
8850: 6f 77 73 20 74 68 6f 73 65 20 74 6f 20 76 61 6c  ows those to val
8860: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20  ues (10 retries 
8870: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  and 25 milliseco
8880: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a  nds of delay).**
8890: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e   to be adjusted.
88a0: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65    The values are
88b0: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c   changed for all
88c0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
88d0: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20  tions.** within 
88e0: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
88f0: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
8900: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
8910: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a  an array of two.
8920: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72  ** integers wher
8930: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65  e the first inte
8940: 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65  ger i the new re
8950: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68  try count and th
8960: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65  e second.** inte
8970: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79  ger is the delay
8980: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74  .  If either int
8990: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eger is negative
89a0: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69  , then the setti
89b0: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  ng.** is not cha
89c0: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64  nged but instead
89d0: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
89e0: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67   of that setting
89f0: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69   is written.** i
8a00: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e  nto the array en
8a10: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68  try, allowing th
8a20: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20  e current retry 
8a30: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a  settings to be.*
8a40: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  * interrogated. 
8a50: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72   The zDbName par
8a60: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65  ameter is ignore
8a70: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  d..**.** ^The [S
8a80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
8a90: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
8aa0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
8ab0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
8ac0: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
8ad0: 20 57 72 69 74 65 20 41 48 65 61 64 20 4c 6f 67   Write AHead Log
8ae0: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
8af0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
8b00: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
8b10: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
8b20: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
8b30: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
8b40: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
8b50: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
8b60: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
8b70: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
8b80: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
8b90: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
8ba0: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
8bb0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
8bc0: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
8bd0: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
8be0: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
8bf0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
8c00: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
8c10: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
8c20: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
8c30: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
8c40: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
8c50: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
8c60: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
8c70: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
8c80: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
8c90: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
8ca0: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
8cb0: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
8cc0: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
8cd0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
8ce0: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
8cf0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
8d00: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
8d10: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8d20: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
8d30: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
8d40: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
8d50: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
8d60: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
8d70: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
8d80: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
8d90: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
8da0: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
8db0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
8dc0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
8dd0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
8de0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
8df0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
8e00: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
8e10: 2a 2a 20 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ** .*/.#define S
8e20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
8e30: 53 54 41 54 45 20 20 20 20 20 20 20 20 31 0a 23  STATE        1.#
8e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45  define SQLITE_GE
8e50: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
8e60: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
8e70: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
8e80: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33 0a 23  OXYFILE      3.#
8e90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41  define SQLITE_LA
8ea0: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
8eb0: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
8ec0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
8ed0: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 35 0a 23  _HINT        5.#
8ee0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
8ef0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
8f00: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
8f10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8f20: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 37 0a 23  _POINTER     7.#
8f30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
8f40: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
8f50: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
8f60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
8f70: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 39 0a 23  2_AV_RETRY   9.#
8f80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
8f90: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20  NTL_PERSIST_WAL 
8fa0: 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41      10../*.** CA
8fb0: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
8fc0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
8fd0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
8fe0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
8ff0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
9000: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
9010: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
9020: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
9030: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
9040: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
9050: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
9060: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
9070: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
9080: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
9090: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
90a0: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
90b0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
90c0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
90d0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
90e0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
90f0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
9100: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
9110: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
9120: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
9130: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
9140: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
9150: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
9160: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
9170: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
9180: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
9190: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
91a0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
91b0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
91c0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
91d0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
91e0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
91f0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
9200: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
9210: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
9220: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
9230: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
9240: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
9250: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
9260: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
9270: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
9280: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
9290: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
92a0: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
92b0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
92c0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
92d0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
92e0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
92f0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
9300: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
9310: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
9320: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
9330: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
9340: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
9350: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
9360: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
9370: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
9380: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
9390: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
93a0: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
93b0: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
93c0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
93d0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
93e0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
93f0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
9400: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
9410: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
9420: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
9430: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
9440: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
9450: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
9460: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
9470: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
9480: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
9490: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
94a0: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
94b0: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
94c0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
94d0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
94e0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
94f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
9500: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
9510: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
9520: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
9530: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
9540: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
9550: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
9560: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
9570: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
9580: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
9590: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
95a0: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
95b0: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
95c0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
95d0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
95e0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
95f0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
9600: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
9610: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
9620: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
9630: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
9640: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
9650: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
9660: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
9670: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
9680: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
9690: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
96a0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
96b0: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
96c0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
96d0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
96e0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
96f0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
9700: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
9710: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
9720: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
9730: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
9740: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
9750: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
9760: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
9770: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
9780: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
9790: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
97a0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
97b0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
97c0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
97d0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
97e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
97f0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
9800: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
9810: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
9820: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
9830: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
9840: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
9850: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
9860: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
9870: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
9880: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
9890: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
98a0: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
98b0: 61 6e 0a 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75  an.** 10 alphanu
98c0: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
98d0: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
98e0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
98f0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
9900: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
9910: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
9920: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
9930: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
9940: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
9950: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
9960: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
9970: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
9980: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
9990: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
99a0: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
99b0: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
99c0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
99d0: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
99e0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
99f0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
9a00: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
9a10: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
9a20: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
9a30: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
9a40: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
9a50: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
9a60: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
9a70: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
9a80: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
9a90: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
9aa0: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
9ab0: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
9ac0: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
9ad0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
9ae0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
9af0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
9b00: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
9b10: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
9b20: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
9b30: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
9b40: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
9b50: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
9b60: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
9b70: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
9b80: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
9b90: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
9ba0: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
9bb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
9bc0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
9bd0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
9be0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
9bf0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
9c00: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
9c10: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
9c20: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
9c30: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
9c40: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
9c50: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
9c60: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
9c70: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
9c80: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
9c90: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
9ca0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
9cb0: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
9cc0: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
9cd0: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
9ce0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
9cf0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
9d00: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
9d10: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
9d20: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
9d30: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
9d40: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
9d50: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
9d60: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
9d70: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
9d80: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
9d90: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
9da0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
9db0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
9dc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
9dd0: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
9de0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
9df0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
9e00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
9e10: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
9e20: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
9e30: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
9e40: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
9e50: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
9e60: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
9e70: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
9e80: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
9e90: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
9ea0: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
9eb0: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
9ec0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
9ed0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
9ee0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
9ef0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
9f00: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
9f10: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
9f20: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
9f30: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
9f40: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
9f50: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
9f60: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
9f70: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
9f80: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
9f90: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
9fa0: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
9fb0: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
9fc0: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
9fd0: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
9fe0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
9ff0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
a000: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
a010: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
a020: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
a030: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
a040: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
a050: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
a060: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
a070: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
a080: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
a090: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
a0a0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
a0b0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
a0c0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
a0d0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
a0e0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
a0f0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
a100: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
a110: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
a120: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
a130: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
a140: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
a150: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
a160: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
a170: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
a180: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
a190: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
a1a0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
a1b0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
a1c0: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
a1d0: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
a1e0: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
a1f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
a200: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
a210: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
a220: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
a230: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
a240: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
a250: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
a260: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
a270: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
a280: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
a290: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
a2a0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
a2b0: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
a2c0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
a2d0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
a2e0: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
a2f0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
a300: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
a310: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
a320: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
a330: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
a340: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
a350: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
a360: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
a370: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
a380: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
a390: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
a3a0: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
a3b0: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
a3c0: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
a3d0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
a3e0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
a3f0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
a400: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
a410: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
a420: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
a430: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
a440: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
a450: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
a460: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
a470: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
a480: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
a490: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
a4a0: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
a4b0: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
a4c0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
a4d0: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
a4e0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
a4f0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
a500: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
a510: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
a520: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
a530: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
a540: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
a550: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
a560: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
a570: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
a580: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
a590: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
a5a0: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
a5b0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
a5c0: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
a5d0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
a5e0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
a5f0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
a600: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
a610: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
a620: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
a630: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
a640: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
a650: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
a660: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
a670: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
a680: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
a690: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
a6a0: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
a6b0: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
a6c0: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
a6d0: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
a6e0: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
a6f0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
a700: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
a710: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
a720: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
a730: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
a740: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
a750: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
a760: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
a770: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
a780: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
a790: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
a7a0: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
a7b0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
a7c0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
a7d0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
a7e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
a7f0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
a800: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
a810: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
a820: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
a830: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
a840: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
a850: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
a860: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
a870: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
a880: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
a890: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
a8a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
a8b0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
a8c0: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
a8d0: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
a8e0: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
a8f0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
a900: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
a910: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
a920: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
a930: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
a940: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
a950: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
a960: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
a970: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
a980: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
a990: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
a9a0: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
a9b0: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
a9c0: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
a9d0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
a9e0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
a9f0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
aa00: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
aa10: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
aa20: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
aa30: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
aa40: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
aa50: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
aa60: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
aa70: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
aa80: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
aa90: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
aaa0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
aab0: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
aac0: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
aad0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
aae0: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
aaf0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
ab00: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
ab10: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
ab20: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
ab30: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
ab40: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
ab50: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
ab60: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
ab70: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
ab80: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
ab90: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
aba0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
abb0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
abc0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
abd0: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
abe0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
abf0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
ac00: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
ac10: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
ac20: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
ac30: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
ac40: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
ac50: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
ac60: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
ac70: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
ac80: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
ac90: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
aca0: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
acb0: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
acc0: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
acd0: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
ace0: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
acf0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
ad00: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
ad10: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
ad20: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
ad30: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
ad40: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
ad50: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
ad60: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
ad70: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
ad80: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
ad90: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
ada0: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
adb0: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
adc0: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
add0: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
ade0: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
adf0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
ae00: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
ae10: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
ae20: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
ae30: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
ae40: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
ae50: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
ae60: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
ae70: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
ae80: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
ae90: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
aea0: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
aeb0: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
aec0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
aed0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
aee0: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
aef0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
af00: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
af10: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
af20: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
af30: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
af40: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
af50: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
af60: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
af70: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
af80: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
af90: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
afa0: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
afb0: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
afc0: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
afd0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
afe0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
aff0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
b000: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
b010: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
b020: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
b030: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
b040: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
b050: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
b060: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
b070: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
b080: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
b090: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
b0a0: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
b0b0: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
b0c0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
b0d0: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
b0e0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
b0f0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
b100: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
b110: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
b120: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
b130: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
b140: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
b150: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
b160: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
b170: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
b180: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
b190: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
b1a0: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
b1b0: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
b1c0: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
b1d0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
b1e0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
b1f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
b200: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
b210: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
b220: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
b230: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
b240: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
b250: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
b260: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
b270: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
b280: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
b290: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
b2a0: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
b2b0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
b2c0: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
b2d0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
b2e0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
b2f0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
b300: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
b310: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
b320: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
b330: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
b340: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
b350: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
b360: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
b370: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
b380: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
b390: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
b3a0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
b3b0: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
b3c0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
b3d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
b3e0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
b3f0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
b400: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
b410: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
b420: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
b430: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
b440: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
b450: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
b460: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
b470: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
b480: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
b490: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
b4a0: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
b4b0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
b4c0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
b4d0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
b4e0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
b4f0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
b500: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
b510: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
b520: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
b530: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
b540: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
b550: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
b560: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
b570: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
b580: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
b590: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
b5a0: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
b5b0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
b5c0: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
b5d0: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
b5e0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
b5f0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
b600: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
b610: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
b620: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
b630: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
b640: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
b650: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
b660: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
b670: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
b680: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
b690: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
b6a0: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
b6b0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
b6c0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
b6d0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
b6e0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
b6f0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
b700: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
b710: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
b720: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
b730: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
b740: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
b750: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
b760: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
b770: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
b780: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
b790: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
b7a0: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
b7b0: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
b7c0: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
b7d0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
b7e0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
b7f0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
b800: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
b810: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
b820: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
b830: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
b840: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
b850: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
b860: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
b870: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
b880: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
b890: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
b8a0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
b8b0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
b8c0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
b8d0: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
b8e0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
b8f0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
b900: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
b910: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
b920: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
b930: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
b940: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
b950: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
b960: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
b970: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
b980: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
b990: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
b9a0: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
b9b0: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
b9c0: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
b9d0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
b9e0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
b9f0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
ba00: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
ba10: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
ba20: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
ba30: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
ba40: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
ba50: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
ba60: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
ba70: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
ba80: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
ba90: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
baa0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
bab0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
bac0: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
bad0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
bae0: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
baf0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
bb00: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
bb10: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
bb20: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
bb30: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
bb40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
bb50: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
bb60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
bb70: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
bb80: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
bb90: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
bba0: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
bbb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
bbc0: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
bbd0: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
bbe0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
bbf0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
bc00: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
bc10: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
bc20: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
bc30: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
bc40: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
bc50: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
bc60: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
bc70: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
bc80: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
bc90: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
bca0: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
bcb0: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
bcc0: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
bcd0: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
bce0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
bcf0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
bd00: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
bd10: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
bd20: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
bd30: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
bd40: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
bd50: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
bd60: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
bd70: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
bd80: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
bd90: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
bda0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
bdb0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
bdc0: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
bdd0: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
bde0: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
bdf0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
be00: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
be10: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
be20: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
be30: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
be40: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
be50: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
be60: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
be70: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
be80: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
be90: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
bea0: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
beb0: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
bec0: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
bed0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
bee0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
bef0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
bf00: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
bf10: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
bf20: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
bf30: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
bf40: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
bf50: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
bf60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
bf70: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
bf80: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
bf90: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
bfa0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
bfb0: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
bfc0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
bfd0: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
bfe0: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
bff0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
c000: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
c010: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
c020: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
c030: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
c040: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
c050: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
c060: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
c070: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
c080: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
c090: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
c0a0: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
c0b0: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
c0c0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c0d0: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
c0e0: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
c0f0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
c100: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
c110: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
c120: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
c130: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
c140: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
c150: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
c160: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
c170: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
c180: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
c190: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
c1a0: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
c1b0: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
c1c0: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
c1d0: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
c1e0: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
c1f0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
c200: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
c210: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
c220: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
c230: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
c240: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c250: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
c260: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
c270: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
c280: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
c290: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
c2a0: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
c2b0: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
c2c0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
c2d0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
c2e0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
c2f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
c300: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
c310: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
c320: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c330: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
c340: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
c350: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
c360: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
c370: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
c380: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
c390: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
c3a0: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
c3b0: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
c3c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
c3d0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
c3e0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
c3f0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
c400: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
c410: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
c420: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
c430: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
c440: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
c450: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
c460: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
c470: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
c480: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
c490: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
c4a0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
c4b0: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
c4c0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
c4d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
c4e0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
c4f0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
c500: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
c510: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
c520: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
c530: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c540: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
c550: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
c560: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
c570: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
c580: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
c590: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
c5a0: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
c5b0: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
c5c0: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
c5d0: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
c5e0: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
c5f0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
c600: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
c610: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
c620: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
c630: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
c640: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
c650: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
c660: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
c670: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
c680: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
c690: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
c6a0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
c6b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
c6c0: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
c6d0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
c6e0: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
c6f0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
c700: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c710: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
c720: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
c730: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
c740: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
c750: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
c760: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
c770: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
c780: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
c790: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
c7a0: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
c7b0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
c7c0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c7d0: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
c7e0: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
c7f0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
c800: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
c810: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
c820: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
c830: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
c840: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
c850: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c860: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
c870: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
c880: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
c890: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
c8a0: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
c8b0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
c8c0: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
c8d0: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
c8e0: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
c8f0: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
c900: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
c910: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
c920: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
c930: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
c940: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
c950: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
c960: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
c970: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
c980: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
c990: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
c9a0: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
c9b0: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
c9c0: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
c9d0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
c9e0: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
c9f0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
ca00: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
ca10: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
ca20: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
ca30: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
ca40: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
ca50: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
ca60: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
ca70: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
ca80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ca90: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
caa0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
cab0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
cac0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
cad0: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
cae0: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
caf0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
cb00: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
cb10: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
cb20: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
cb30: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
cb40: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
cb50: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
cb60: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
cb70: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
cb80: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
cb90: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
cba0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
cbb0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
cbc0: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
cbd0: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
cbe0: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
cbf0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
cc00: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
cc10: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
cc20: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
cc30: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
cc40: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
cc50: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
cc60: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
cc70: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
cc80: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
cc90: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
cca0: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
ccb0: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
ccc0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
ccd0: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
cce0: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
ccf0: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
cd00: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
cd10: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
cd20: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
cd30: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
cd40: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
cd50: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
cd60: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
cd70: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
cd80: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
cd90: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
cda0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
cdb0: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
cdc0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
cdd0: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
cde0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
cdf0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
ce00: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
ce10: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
ce20: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
ce30: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
ce40: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
ce50: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ce60: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
ce70: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
ce80: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
ce90: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
cea0: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
ceb0: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
cec0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
ced0: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
cee0: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
cef0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
cf00: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
cf10: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
cf20: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
cf30: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
cf40: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
cf50: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
cf60: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
cf70: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
cf80: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
cf90: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
cfa0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
cfb0: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
cfc0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
cfd0: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
cfe0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
cff0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
d000: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
d010: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
d020: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
d030: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
d040: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
d050: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
d060: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
d070: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
d080: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
d090: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
d0a0: 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ilure..*/.SQLITE
d0b0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
d0c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
d0d0: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
d0e0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
d0f0: 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  wn(void);.SQLITE
d100: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
d110: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
d120: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
d130: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
d140: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
d150: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
d160: 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
d170: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
d180: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
d190: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
d1a0: 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
d1b0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
d1c0: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
d1d0: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
d1e0: 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
d1f0: 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
d200: 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
d210: 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
d220: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
d230: 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
d240: 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
d250: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
d260: 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
d270: 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
d280: 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
d290: 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
d2a0: 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
d2b0: 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
d2c0: 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
d2d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d2e0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
d2f0: 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
d300: 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69  safe.  The appli
d310: 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69  cation.** must i
d320: 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
d330: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
d340: 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
d350: 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
d360: 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
d370: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
d380: 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65  running.  Furthe
d390: 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63  rmore, sqlite3_c
d3a0: 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f  onfig().** may o
d3b0: 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
d3c0: 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
d3d0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
d3e0: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
d3f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
d400: 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
d410: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
d420: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
d430: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
d440: 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
d450: 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
d460: 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
d470: 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
d480: 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
d490: 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
d4a0: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
d4b0: 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
d4c0: 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
d4d0: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
d4e0: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
d4f0: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
d500: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
d510: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
d520: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
d530: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
d540: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
d550: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
d560: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
d570: 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
d580: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
d590: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
d5a0: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
d5b0: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
d5c0: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
d5d0: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
d5e0: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
d5f0: 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
d600: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
d610: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
d620: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
d630: 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
d640: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
d650: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
d660: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
d670: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
d680: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
d690: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
d6a0: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
d6b0: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
d6c0: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
d6d0: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
d6e0: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
d6f0: 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  de]..*/.SQLITE_A
d700: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
d710: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
d720: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d730: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
d740: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
d750: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
d760: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
d770: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
d780: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
d790: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
d7a0: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
d7b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
d7c0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
d7d0: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
d7e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
d7f0: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
d800: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
d810: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
d820: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d830: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
d840: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
d850: 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
d860: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
d870: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
d880: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
d890: 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
d8a0: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
d8b0: 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
d8c0: 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
d8d0: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
d8e0: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
d8f0: 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
d900: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
d910: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
d920: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
d930: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
d940: 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
d950: 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
d960: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
d970: 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
d980: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
d990: 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
d9a0: 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
d9b0: 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
d9c0: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
d9d0: 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  ccessful..*/.SQL
d9e0: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
d9f0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
da00: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
da10: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
da20: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
da30: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
da40: 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
da50: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
da60: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
da70: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
da80: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
da90: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
daa0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
dab0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
dac0: 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
dad0: 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
dae0: 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
daf0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
db00: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
db10: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
db20: 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
db30: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
db40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
db50: 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
db60: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
db70: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
db80: 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
db90: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
dba0: 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
dbb0: 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
dbc0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
dbd0: 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
dbe0: 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
dbf0: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
dc00: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
dc10: 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
dc20: 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
dc30: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
dc40: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
dc50: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
dc60: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
dc70: 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
dc80: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
dc90: 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
dca0: 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
dcb0: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
dcc0: 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
dcd0: 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
dce0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
dcf0: 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
dd00: 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
dd10: 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
dd20: 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
dd30: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
dd40: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
dd50: 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
dd60: 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
dd70: 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
dd80: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
dd90: 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
dda0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ddb0: 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
ddc0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
ddd0: 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
dde0: 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
ddf0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
de00: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
de10: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
de20: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
de30: 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
de40: 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
de50: 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
de60: 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
de70: 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
de80: 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
de90: 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
dea0: 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
deb0: 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
dec0: 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
ded0: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
dee0: 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
def0: 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
df00: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
df10: 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
df20: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
df30: 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
df40: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
df50: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
df60: 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
df70: 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
df80: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
df90: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
dfa0: 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
dfb0: 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
dfc0: 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
dfd0: 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
dfe0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
dff0: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
e000: 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
e010: 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
e020: 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
e030: 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
e040: 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
e050: 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
e060: 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
e070: 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
e080: 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
e090: 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
e0a0: 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
e0b0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
e0c0: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
e0d0: 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
e0e0: 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
e0f0: 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
e100: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
e110: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
e120: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
e130: 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
e140: 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
e150: 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
e160: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
e170: 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
e180: 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
e190: 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
e1a0: 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
e1b0: 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
e1c0: 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
e1d0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
e1e0: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
e1f0: 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
e200: 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
e210: 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
e220: 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
e230: 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
e240: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
e250: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
e260: 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
e270: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
e280: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
e290: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
e2a0: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
e2b0: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
e2c0: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
e2d0: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
e2e0: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
e2f0: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
e300: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
e310: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
e320: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
e330: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
e340: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
e350: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
e360: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
e370: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
e380: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
e390: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
e3a0: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
e3b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
e3c0: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
e3d0: 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
e3e0: 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
e3f0: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
e400: 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
e410: 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
e420: 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
e430: 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
e440: 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
e450: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
e460: 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
e470: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
e480: 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
e490: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e4a0: 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
e4b0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
e4c0: 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
e4d0: 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
e4e0: 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
e4f0: 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
e500: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
e510: 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
e520: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
e530: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
e540: 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
e550: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
e560: 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
e570: 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
e580: 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
e590: 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
e5a0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
e5b0: 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
e5c0: 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
e5d0: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
e5e0: 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
e5f0: 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
e600: 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
e610: 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
e620: 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
e630: 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
e640: 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
e650: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
e660: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
e670: 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
e680: 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
e690: 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
e6a0: 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
e6b0: 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
e6c0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
e6d0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
e6e0: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
e6f0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
e700: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
e710: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
e720: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
e730: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
e740: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
e750: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
e760: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
e770: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
e780: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
e790: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
e7a0: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
e7b0: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
e7c0: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
e7d0: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
e7e0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
e7f0: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
e800: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
e810: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
e820: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
e830: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
e840: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
e850: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
e860: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
e870: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
e880: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
e890: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
e8a0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
e8b0: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
e8c0: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
e8d0: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
e8e0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
e8f0: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
e900: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
e910: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
e920: 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
e930: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
e940: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
e950: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
e960: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
e970: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
e980: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
e990: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
e9a0: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
e9b0: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
e9c0: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
e9d0: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
e9e0: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
e9f0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
ea00: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
ea10: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
ea20: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
ea30: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
ea40: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
ea50: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
ea60: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
ea70: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
ea80: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ea90: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
eaa0: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
eab0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
eac0: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
ead0: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
eae0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
eaf0: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
eb00: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
eb10: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
eb20: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
eb30: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
eb40: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
eb50: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
eb60: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
eb70: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
eb80: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
eb90: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
eba0: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
ebb0: 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
ebc0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
ebd0: 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
ebe0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
ebf0: 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
ec00: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
ec10: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
ec20: 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
ec30: 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
ec40: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
ec50: 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
ec60: 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
ec70: 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
ec80: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
ec90: 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
eca0: 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
ecb0: 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
ecc0: 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
ecd0: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
ece0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
ecf0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
ed00: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
ed10: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
ed20: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
ed30: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
ed40: 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
ed50: 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
ed60: 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
ed70: 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
ed80: 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
ed90: 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
eda0: 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
edb0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
edc0: 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
edd0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
ede0: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
edf0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
ee00: 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
ee10: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ee20: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
ee30: 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
ee40: 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
ee50: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
ee60: 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
ee70: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
ee80: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
ee90: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
eea0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
eeb0: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
eec0: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
eed0: 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
eee0: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
eef0: 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
ef00: 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
ef10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
ef20: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
ef30: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
ef40: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
ef50: 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
ef60: 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
ef70: 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
ef80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ef90: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
efa0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
efb0: 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
efc0: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
efd0: 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
efe0: 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
eff0: 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
f000: 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
f010: 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
f020: 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
f030: 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
f040: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
f050: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f060: 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
f070: 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
f080: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
f090: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
f0a0: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
f0b0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
f0c0: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
f0d0: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
f0e0: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
f0f0: 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
f100: 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
f110: 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
f120: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
f130: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
f140: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
f150: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
f160: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
f170: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
f180: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f190: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
f1a0: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
f1b0: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
f1c0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
f1d0: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
f1e0: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
f1f0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
f200: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
f210: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
f220: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
f230: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
f240: 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
f250: 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
f260: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
f270: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
f280: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
f290: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
f2a0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f2b0: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
f2c0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
f2d0: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
f2e0: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
f2f0: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
f300: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
f310: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
f320: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
f330: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
f340: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
f350: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
f360: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
f370: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f380: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
f390: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
f3a0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
f3b0: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
f3c0: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
f3d0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f3e0: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
f3f0: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
f400: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
f410: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
f420: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
f430: 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
f440: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
f450: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
f460: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
f470: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
f480: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
f490: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
f4a0: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
f4b0: 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
f4c0: 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
f4d0: 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
f4e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f4f0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
f500: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
f510: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
f520: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
f530: 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
f540: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
f550: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
f560: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
f570: 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
f580: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
f590: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
f5a0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
f5b0: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
f5c0: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
f5d0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
f5e0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
f5f0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
f600: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
f610: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
f620: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
f630: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
f640: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f650: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
f660: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
f670: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
f680: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
f690: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
f6a0: 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
f6b0: 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
f6c0: 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
f6d0: 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
f6e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
f6f0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
f700: 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
f710: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
f720: 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
f730: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
f740: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
f750: 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
f760: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
f770: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
f780: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
f790: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
f7a0: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
f7b0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
f7c0: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
f7d0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
f7e0: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
f7f0: 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
f800: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
f810: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
f820: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
f830: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
f840: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
f850: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
f860: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
f870: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
f880: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
f890: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
f8a0: 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
f8b0: 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
f8c0: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
f8d0: 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
f8e0: 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
f8f0: 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
f900: 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
f910: 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
f920: 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
f930: 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
f940: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
f950: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
f960: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
f970: 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
f980: 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
f990: 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
f9a0: 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
f9b0: 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
f9c0: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
f9d0: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
f9e0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f9f0: 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
fa00: 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
fa10: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
fa20: 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
fa30: 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
fa40: 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
fa50: 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
fa60: 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
fa70: 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
fa80: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
fa90: 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
faa0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
fab0: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
fac0: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
fad0: 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
fae0: 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
faf0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
fb00: 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
fb10: 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
fb20: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
fb30: 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
fb40: 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
fb50: 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
fb60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
fb70: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
fb80: 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
fb90: 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
fba0: 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
fbb0: 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
fbc0: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
fbd0: 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
fbe0: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
fbf0: 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
fc00: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
fc10: 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
fc20: 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
fc30: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
fc40: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
fc50: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
fc60: 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
fc70: 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
fc80: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
fc90: 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
fca0: 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
fcb0: 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
fcc0: 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
fcd0: 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
fce0: 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
fcf0: 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
fd00: 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
fd10: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
fd20: 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
fd30: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
fd40: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
fd50: 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
fd60: 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
fd70: 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
fd80: 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
fd90: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
fda0: 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
fdb0: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
fdc0: 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
fdd0: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
fde0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
fdf0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
fe00: 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
fe10: 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
fe20: 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
fe30: 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
fe40: 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
fe50: 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
fe60: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
fe70: 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
fe80: 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
fe90: 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
fea0: 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
feb0: 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
fec0: 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
fed0: 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
fee0: 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
fef0: 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
ff00: 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
ff10: 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
ff20: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
ff30: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
ff40: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
ff50: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
ff60: 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
ff70: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
ff80: 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
ff90: 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
ffa0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
ffb0: 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
ffc0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
ffd0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
ffe0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
fff0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
10000 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
10010 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
10020 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
10030 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
10040 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
10050 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
10060 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
10070 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
10080 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
10090 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
100a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
100b0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
100c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
100d0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
100e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
100f0 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  ACHE option..** 
10100 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
10110 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
10120 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e  s option: A poin
10130 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c  ter to 8-byte al
10140 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c  igned.** memory,
10150 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
10160 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73  h page buffer (s
10170 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  z), and the numb
10180 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e  er of pages (N).
10190 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
101a0 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
101b0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
101c0 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
101d0 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
101e0 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
101f0 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c  12 and 32768) pl
10200 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72  us a little extr
10210 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  a for each.** pa
10220 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
10230 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a   page header siz
10240 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79  e is 20 to 40 by
10250 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  tes depending on
10260 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63  .** the host arc
10270 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20  hitecture.  ^It 
10280 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
10290 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
102a0 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f  ed memory,.** to
102b0 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c   make sz a littl
102c0 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68  e too large.  Th
102d0 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
102e0 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
102f0 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
10300 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  n of at least sz
10310 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
10320 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
10330 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
10340 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
10350 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10360 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73  t to satisfy its
10370 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  .** memory needs
10380 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
10390 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
103a0 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e  dds to cache.  ^
103b0 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
103c0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
103d0 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
103e0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
103f0 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
10400 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
10410 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
10420 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
10430 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
10440 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
10450 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
10460 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
10470 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65  ument must.** be
10480 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
10490 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f  -byte boundary o
104a0 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
104b0 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
104c0 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  ** will be undef
104d0 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ined.</dd>.**.**
104e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
104f0 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
10500 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
10510 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
10520 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
10530 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
10540 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
10550 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
10560 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  * for all of its
10570 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
10580 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
10590 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
105a0 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79  ovided.** for by
105b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
105c0 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51  SCRATCH] and [SQ
105d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
105e0 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65  CACHE]..** There
105f0 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
10600 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20  ents: An 8-byte 
10610 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
10620 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
10630 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
10640 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
10650 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
10660 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
10670 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
10680 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
10690 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
106a0 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
106b0 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
106c0 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
106d0 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
106e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
106f0 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
10700 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
10710 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
10720 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
10730 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
10740 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
10750 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
10760 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
10770 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74  not NULL and eit
10780 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
10790 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a  LE_MEMSYS3] or.*
107a0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
107b0 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65  _MEMSYS5] are de
107c0 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  fined, then the 
107d0 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
107e0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
107f0 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
10800 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
10810 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
10820 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
10830 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
10840 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
10850 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
10860 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
10870 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
10880 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
10890 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
108a0 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
108b0 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d  ed..** The minim
108c0 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
108d0 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20  ze is capped at 
108e0 32 5e 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  2^12. Reasonable
108f0 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
10900 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
10910 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
10920 5e 35 20 74 68 72 6f 75 67 68 20 32 5e 38 2e 3c  ^5 through 2^8.<
10930 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
10940 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
10950 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
10960 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
10970 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
10980 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
10990 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
109a0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
109b0 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
109c0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
109d0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
109e0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
109f0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
10a00 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
10a10 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
10a20 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
10a30 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
10a40 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
10a50 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
10a60 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
10a70 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
10a80 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
10a90 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
10aa0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
10ab0 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
10ac0 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
10ad0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
10ae0 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
10af0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
10b00 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
10b10 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
10b20 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
10b30 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
10b40 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
10b50 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
10b60 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
10b70 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
10b80 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
10b90 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
10ba0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
10bb0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
10bc0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10bd0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
10be0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
10bf0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
10c00 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
10c10 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
10c20 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20  NFIG_GETMUTEX]] 
10c30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10c40 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
10c50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
10c60 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
10c70 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
10c80 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
10c90 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
10ca0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
10cb0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
10cc0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
10cd0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
10ce0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
10cf0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
10d00 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
10d10 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
10d20 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
10d30 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
10d40 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
10d50 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
10d60 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
10d70 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
10d80 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
10d90 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
10da0 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
10db0 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
10dc0 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
10dd0 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
10de0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
10df0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
10e00 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
10e10 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
10e20 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
10e30 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
10e40 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
10e50 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
10e60 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
10e70 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
10e80 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
10e90 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
10ea0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
10eb0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
10ec0 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
10ed0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10ee0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
10ef0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
10f00 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
10f10 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
10f20 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
10f30 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
10f40 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
10f50 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
10f60 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
10f70 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
10f80 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20   the default.** 
10f90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10fa0 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73  n for the lookas
10fb0 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
10fc0 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20  ator on each.** 
10fd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10fe0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73  tion].  The firs
10ff0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
11000 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
11010 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
11020 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
11030 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
11040 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
11050 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
11060 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
11070 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69  ection.)^  ^(Thi
11080 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
11090 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c  e.** <i>default<
110a0 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69  /i> lookaside si
110b0 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  ze. The [SQLITE_
110c0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
110d0 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b  DE].** verb to [
110e0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
110f0 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
11100 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
11110 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
11120 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
11130 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
11140 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
11150 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11160 49 47 5f 50 43 41 43 48 45 5d 5d 20 3c 64 74 3e  IG_PCACHE]] <dt>
11170 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
11180 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
11190 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
111a0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
111b0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
111c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
111d0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
111e0 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
111f0 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
11200 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
11210 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
11220 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
11230 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
11240 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
11250 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
11260 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
11270 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
11280 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
11290 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
112a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
112b0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
112c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
112d0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f  NFIG_GETPCACHE</
112e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
112f0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
11300 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
11310 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
11320 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
11330 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
11340 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
11350 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
11360 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
11370 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
11380 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
11390 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
113a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
113b0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
113c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
113d0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
113e0 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
113f0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
11400 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
11410 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
11420 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
11430 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
11440 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
11450 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
11460 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
11470 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
11480 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
11490 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
114a0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
114b0 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
114c0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
114d0 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
114e0 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
114f0 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
11500 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
11510 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
11520 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
11530 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
11540 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
11550 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
11560 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
11570 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
11580 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
11590 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
115a0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
115b0 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
115c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
115d0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
115e0 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
115f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
11600 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
11610 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
11620 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
11630 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
11640 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
11650 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
11660 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
11670 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
11680 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
11690 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
116a0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
116b0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
116c0 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
116d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
116e0 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
116f0 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
11700 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
11710 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
11720 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
11730 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
11740 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
11750 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
11760 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
11770 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
11780 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
11790 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
117a0 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
117b0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
117c0 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
117d0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
117e0 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
117f0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
11800 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
11810 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
11820 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
11830 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
11840 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
11850 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
11860 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  > This option ta
11870 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
11880 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
11890 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  t. If non-zero, 
118a0 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64  then.** URI hand
118b0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
118c0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
118d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
118e0 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
118f0 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62  dling.** is glob
11900 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20 49  ally disabled. I
11910 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
11920 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
11930 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
11940 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b  s.** passed to [
11950 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
11960 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
11970 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  2()], [sqlite3_o
11980 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
11990 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
119a0 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
119b0 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
119c0 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
119d0 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
119e0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
119f0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
11a00 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
11a10 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
11a20 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
11a30 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20 69   is opened. If i
11a40 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
11a50 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
11a60 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
11a70 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
11a80 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
11a90 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
11aa0 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
11ab0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11ac0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
11ad0 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
11ae0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
11af0 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
11b00 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
11b10 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
11b20 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
11b30 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
11b40 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
11b50 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  bol defined..** 
11b60 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
11b70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
11b80 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
11b90 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
11ba0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11bb0 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
11bc0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
11bd0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
11be0 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
11bf0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
11c00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
11c10 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
11c20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
11c30 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
11c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
11c50 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
11c60 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
11c70 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
11c80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11c90 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
11ca0 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
11cb0 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
11cc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
11cd0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
11ce0 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
11cf0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
11d00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11d10 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
11d20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
11d30 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
11d40 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
11d50 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
11d60 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
11d70 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
11d80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11d90 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
11da0 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
11db0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
11dc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11dd0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
11de0 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
11df0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
11e00 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
11e10 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
11e20 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
11e30 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
11e40 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
11e50 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
11e60 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
11e70 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
11e80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11e90 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
11ea0 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65     14  /* sqlite
11eb0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
11ec0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
11ed0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
11ee0 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73  ACHE    15  /* s
11ef0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
11f00 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
11f10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11f20 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
11f30 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
11f40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11f50 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
11f60 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
11f70 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t */../*.** CAPI
11f80 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
11f90 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
11fa0 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
11fb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
11fc0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
11fd0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
11fe0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11ff0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
12000 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
12010 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
12020 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
12030 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
12040 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
12050 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
12060 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
12070 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
12080 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
12090 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
120a0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
120b0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
120c0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
120d0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
120e0 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
120f0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
12100 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
12110 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
12120 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
12130 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
12140 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
12150 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
12160 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
12170 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
12180 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
12190 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
121a0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
121b0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
121c0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
121d0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
121e0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
121f0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
12200 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
12210 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
12220 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
12230 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
12240 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
12250 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
12260 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
12270 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
12280 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12290 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
122a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
122b0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
122c0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
122d0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
122e0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
122f0 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
12300 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
12310 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
12320 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
12330 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
12340 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
12350 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
12360 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
12370 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
12380 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
12390 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
123a0 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
123b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
123c0 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
123d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
123e0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
123f0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
12400 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
12410 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
12420 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
12430 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
12440 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
12450 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
12460 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
12470 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
12480 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
12490 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
124a0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
124b0 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
124c0 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
124d0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
124e0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
124f0 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
12500 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
12510 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
12520 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
12530 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
12540 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
12550 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
12560 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
12570 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
12580 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
12590 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
125a0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
125b0 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
125c0 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
125d0 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
125e0 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
125f0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
12600 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
12610 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
12620 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
12630 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
12640 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
12650 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
12660 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
12670 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
12680 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
12690 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
126a0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
126b0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
126c0 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
126d0 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
126e0 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
126f0 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
12700 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
12710 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
12720 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
12730 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
12740 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
12750 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
12760 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
12770 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
12780 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
12790 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
127a0 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
127b0 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
127c0 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
127d0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
127e0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
127f0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
12800 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12810 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
12820 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
12830 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
12840 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
12850 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
12860 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
12870 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
12880 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
12890 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
128a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
128b0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
128c0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
128d0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
128e0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
128f0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
12900 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
12910 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
12920 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
12930 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
12940 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
12950 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
12960 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
12970 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
12980 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
12990 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
129a0 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
129b0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
129c0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
129d0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
129e0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
129f0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
12a00 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
12a10 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
12a20 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
12a30 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
12a40 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
12a50 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
12a60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
12a70 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
12a80 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
12a90 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
12aa0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
12ab0 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
12ac0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
12ad0 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
12ae0 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
12af0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
12b00 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12b10 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
12b20 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
12b30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
12b40 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
12b50 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
12b60 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
12b70 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
12b80 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
12b90 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
12ba0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
12bb0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
12bc0 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
12bd0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
12be0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
12bf0 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
12c00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
12c10 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
12c20 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
12c30 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
12c40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12c50 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
12c60 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
12c70 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
12c80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
12c90 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
12ca0 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
12cb0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
12cc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
12cd0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
12ce0 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
12cf0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Codes.**.** ^The
12d00 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
12d10 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
12d20 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
12d30 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
12d40 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
12d50 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
12d60 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
12d70 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
12d80 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
12d90 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
12da0 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
12db0 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
12dc0 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  y..*/.SQLITE_API
12dd0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
12de0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
12df0 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
12e00 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
12e10 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
12e20 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
12e30 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
12e40 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65   an SQLite table
12e50 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
12e60 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
12e70 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
12e80 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
12e90 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
12ea0 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
12eb0 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
12ec0 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
12ed0 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
12ee0 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
12ef0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
12f00 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
12f10 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
12f20 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
12f30 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
12f40 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
12f50 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
12f60 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
12f70 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
12f80 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
12f90 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
12fa0 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
12fb0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
12fc0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
12fd0 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20  id] of the most 
12fe0 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73  recent.** succes
12ff0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
13000 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
13010 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61  from the [databa
13020 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
13030 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
13040 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66  rgument.  ^As of
13050 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
13060 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74  3.7.7, this rout
13070 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20  ines.** records 
13080 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
13090 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72  rowid of both or
130a0 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e  dinary tables an
130b0 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  d [virtual table
130c0 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75  s]..** ^If no su
130d0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
130e0 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  ]s.** have ever 
130f0 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74  occurred on that
13100 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13110 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65  tion, zero is re
13120 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  turned..**.** ^(
13130 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
13140 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
13150 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
13160 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
13170 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
13180 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
13190 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
131a0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
131b0 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
131c0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
131d0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
131e0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
131f0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
13200 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
13210 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
13220 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
13230 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
13240 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
13250 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
13260 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
13270 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
13280 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
13290 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
132a0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
132b0 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
132c0 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
132d0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
132e0 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
132f0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
13300 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
13310 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
13320 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
13330 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
13340 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
13350 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
13360 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
13370 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
13380 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
13390 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
133a0 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
133b0 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
133c0 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
133d0 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
133e0 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
133f0 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
13400 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
13410 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
13420 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
13430 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
13440 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
13450 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
13460 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
13470 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
13480 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
13490 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
134a0 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
134b0 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
134c0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
134d0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
134e0 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
134f0 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
13500 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
13510 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
13520 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
13530 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
13540 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
13550 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
13560 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
13570 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
13580 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
13590 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
135a0 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
135b0 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
135c0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
135d0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
135e0 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
135f0 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
13600 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
13610 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
13620 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
13630 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
13640 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
13650 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
13660 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
13670 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
13680 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
13690 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
136a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
136b0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
136c0 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
136d0 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
136e0 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
136f0 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
13700 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
13710 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
13720 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
13730 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
13740 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
13750 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
13760 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13770 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
13780 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
13790 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
137a0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
137b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
137c0 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
137d0 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
137e0 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
137f0 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
13800 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
13810 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
13820 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
13830 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13840 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
13850 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
13860 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  eter..** ^(Only 
13870 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
13880 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
13890 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45  ied by the [INSE
138a0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a  RT], [UPDATE],.*
138b0 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  * or [DELETE] st
138c0 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
138d0 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
138e0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
138f0 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72  y.** triggers or
13900 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
13910 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63  tions] are not c
13920 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68  ounted.)^ Use th
13930 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f  e.** [sqlite3_to
13940 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
13950 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20  unction to find 
13960 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
13970 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69   of changes.** i
13980 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
13990 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
139a0 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20  ers and foreign 
139b0 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  key actions..**.
139c0 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  ** ^Changes to a
139d0 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73   view that are s
139e0 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b  imulated by an [
139f0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
13a00 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  er].** are not c
13a10 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65  ounted.  Only re
13a20 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73  al table changes
13a30 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
13a40 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61  .** ^(A "row cha
13a50 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
13a60 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
13a70 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
13a80 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
13a90 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
13aa0 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
13ab0 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
13ac0 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
13ad0 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
13ae0 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63  s of [REPLACE] c
13af0 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
13b00 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
13b10 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
13b20 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45  ing, [DROP TABLE
13b30 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  ], or by any oth
13b40 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
13b50 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
13b60 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
13b70 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22  ges.)^.**.** A "
13b80 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22  trigger context"
13b90 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65   is a scope of e
13ba0 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65  xecution that be
13bb0 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73  gins and.** ends
13bc0 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74   with the script
13bd0 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52   of a [CREATE TR
13be0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
13bf0 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73  . .** Most SQL s
13c00 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
13c10 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
13c20 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
13c30 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
13c40 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
13c50 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
13c60 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
13c70 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
13c80 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
13c90 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
13ca0 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
13cb0 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
13cc0 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
13cd0 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
13ce0 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
13cf0 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
13d00 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  uration..**.** ^
13d10 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
13d20 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
13d30 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
13d40 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
13d50 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
13d60 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
13d70 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  t..**.** ^This f
13d80 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
13d90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
13da0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
13db0 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
13dc0 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
13dd0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
13de0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
13df0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
13e00 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
13e10 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e  *.** ^Thus, when
13e20 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
13e30 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
13e40 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
13e50 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
13e60 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
13e70 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
13e80 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
13e90 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
13ea0 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
13eb0 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
13ec0 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f   ^(Within the bo
13ed0 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
13ee0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
13ef0 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
13f00 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
13f10 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
13f20 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
13f30 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
13f40 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
13f50 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
13f60 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
13f70 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
13f80 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
13f90 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
13fa0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
13fb0 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
13fc0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
13fd0 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
13fe0 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
13ff0 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
14000 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
14010 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  xt.)^.**.** See 
14020 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
14030 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
14040 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
14050 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
14060 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
14070 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
14080 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
14090 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
140a0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
140b0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
140c0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
140d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
140e0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
140f0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
14100 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
14110 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
14120 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
14130 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
14140 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
14150 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
14160 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
14170 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
14180 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
14190 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
141a0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
141b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
141c0 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
141d0 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e  es caused by [IN
141e0 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54  SERT],.** [UPDAT
141f0 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
14200 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
14210 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
14220 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
14230 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63  ened..** ^(The c
14240 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79  ount returned by
14250 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
14260 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65  hanges() include
14270 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a  s all changes.**
14280 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54   from all [CREAT
14290 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
142a0 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e  ger] contexts an
142b0 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62  d changes made b
142c0 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  y.** [foreign ke
142d0 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65  y actions]. Howe
142e0 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
142f0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
14300 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
14310 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45  to implement [RE
14320 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
14330 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
14340 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
14350 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f  cessing, or [DRO
14360 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73  P TABLE] process
14370 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75  ing.  The.** cou
14380 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
14390 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77  ude rows of view
143a0 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b  s that fire an [
143b0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
143c0 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69  er],.** though i
143d0 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46  f the INSTEAD OF
143e0 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63   trigger makes c
143f0 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77  hanges of its ow
14400 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  n, those changes
14410 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64   .** are counted
14420 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .)^.** ^The sqli
14430 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
14440 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75  s() function cou
14450 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20  nts the changes 
14460 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68  as soon as.** th
14470 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
14480 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63   makes them is c
14490 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
144a0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
144b0 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64  dle.** is passed
144c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
144d0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
144e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
144f0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
14500 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
14510 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
14520 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
14530 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
14540 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
14550 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
14560 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
14570 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
14580 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
14590 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
145a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
145b0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
145c0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
145d0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
145e0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
145f0 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
14600 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
14610 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
14620 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
14630 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
14640 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
14650 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
14660 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
14670 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
14680 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ry.**.** ^This f
14690 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
146a0 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
146b0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
146c0 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
146d0 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
146e0 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
146f0 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
14700 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
14710 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
14720 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
14730 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
14740 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
14750 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
14760 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
14770 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
14780 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
14790 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
147a0 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
147b0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
147c0 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
147d0 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
147e0 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
147f0 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
14800 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
14810 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
14820 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
14830 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
14840 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
14850 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
14860 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
14870 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
14880 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
14890 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
148a0 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
148b0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
148c0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
148d0 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
148e0 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
148f0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
14900 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
14910 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
14920 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
14930 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
14940 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
14950 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
14960 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
14970 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
14980 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
14990 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
149a0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
149b0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
149c0 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
149d0 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
149e0 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
149f0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
14a00 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
14a10 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
14a20 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
14a30 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
14a40 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
14a50 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
14a60 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
14a70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
14a80 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
14a90 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
14aa0 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
14ab0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
14ac0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
14ad0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
14ae0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
14af0 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
14b00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
14b10 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
14b20 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
14b30 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
14b40 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
14b50 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
14b60 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
14b70 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
14b80 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
14b90 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
14ba0 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
14bb0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
14bc0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
14bd0 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
14be0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
14bf0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
14c00 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
14c10 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
14c20 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
14c30 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
14c40 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
14c50 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
14c60 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
14c70 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
14c80 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
14c90 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
14ca0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
14cb0 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
14cc0 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
14cd0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
14ce0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
14cf0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
14d00 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
14d10 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
14d20 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
14d30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14d40 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
14d50 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
14d60 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
14d70 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
14d80 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
14d90 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  appen..*/.SQLITE
14da0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
14db0 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
14dc0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
14dd0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
14de0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
14df0 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
14e00 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
14e10 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
14e20 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
14e30 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
14e40 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
14e50 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
14e60 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
14e70 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
14e80 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
14e90 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
14ea0 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
14eb0 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
14ec0 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
14ed0 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
14ee0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
14ef0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
14f00 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
14f10 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
14f20 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
14f30 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
14f40 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
14f50 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
14f60 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
14f70 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
14f80 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
14f90 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
14fa0 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
14fb0 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
14fc0 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
14fd0 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
14fe0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
14ff0 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
15000 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
15010 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
15020 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
15030 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
15040 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
15050 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
15060 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
15070 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
15080 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
15090 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
150a0 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
150b0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
150c0 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
150d0 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
150e0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
150f0 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
15100 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
15110 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
15120 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
15130 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
15140 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
15150 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
15160 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
15170 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
15180 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
15190 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
151a0 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
151b0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
151c0 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
151d0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
151e0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
151f0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
15200 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
15210 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
15220 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
15230 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
15240 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
15250 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
15260 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
15270 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
15280 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
15290 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
152a0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
152b0 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
152c0 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
152d0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
152e0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
152f0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
15300 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
15310 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
15320 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
15330 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
15340 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
15350 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
15360 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
15370 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
15380 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
15390 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
153a0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
153b0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
153c0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
153d0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
153e0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
153f0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
15400 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
15410 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
15420 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
15430 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
15440 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ql);.SQLITE_API 
15450 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
15460 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
15470 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
15480 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
15490 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
154a0 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
154b0 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a  USY Errors.**.**
154c0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
154d0 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
154e0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67  unction that mig
154f0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  ht be invoked wh
15500 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
15510 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
15520 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  open a database 
15530 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68  table that anoth
15540 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20  er thread.** or 
15550 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b  process has lock
15560 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
15570 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
15580 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
15590 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
155a0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
155b0 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75  CKED].** is retu
155c0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
155d0 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
155e0 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49  ng the lock.  ^I
155f0 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
15600 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
15610 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
15620 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69  lback might be i
15630 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
15640 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
15650 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
15660 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79  ment to the busy
15670 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
15680 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
15690 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
156a0 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
156b0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
156c0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
156d0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  .  ^The second a
156e0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
156f0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
15700 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
15710 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
15720 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
15730 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
15740 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69   invoked for thi
15750 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  s locking event.
15760 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
15770 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
15780 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
15790 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
157a0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
157b0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
157c0 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
157d0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
157e0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
157f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
15800 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
15810 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
15820 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
15830 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
15840 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ade to open the 
15850 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
15860 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
15870 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
15880 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
15890 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
158a0 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
158b0 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
158c0 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
158d0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
158e0 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
158f0 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
15900 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
15910 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
15920 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
15930 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
15940 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
15950 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
15960 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f  QLITE_BUSY].** o
15970 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
15980 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64  BLOCKED] instead
15990 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
159a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
159b0 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
159c0 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
159d0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
159e0 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
159f0 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
15a00 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
15a10 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
15a20 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
15a30 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
15a40 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
15a50 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
15a60 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
15a70 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
15a80 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
15a90 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
15aa0 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
15ab0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
15ac0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
15ad0 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
15ae0 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
15af0 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
15b00 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
15b10 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
15b20 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
15b30 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
15b40 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
15b50 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
15b60 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
15b70 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
15b80 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
15b90 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
15ba0 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
15bb0 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
15bc0 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
15bd0 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
15be0 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
15bf0 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
15c00 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
15c10 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
15c20 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
15c30 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
15c40 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
15c50 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
15c60 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
15c70 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64  ror is converted
15c80 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   to [SQLITE_IOER
15c90 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68  R_BLOCKED].** wh
15ca0 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20  en SQLite is in 
15cb0 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20  the middle of a 
15cc0 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f  large transactio
15cd0 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a  n where all the.
15ce0 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ** changes will 
15cf0 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65  not fit into the
15d00 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65   in-memory cache
15d10 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
15d20 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61  * already hold a
15d30 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f   RESERVED lock o
15d40 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
15d50 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64  ile, but it need
15d60 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  s.** to promote 
15d70 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43  this lock to EXC
15d80 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69  LUSIVE so that i
15d90 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68  t can spill cach
15da0 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20  e.** pages into 
15db0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
15dc0 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74  e without harm t
15dd0 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20  o concurrent.** 
15de0 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74  readers.  ^If it
15df0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
15e00 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
15e10 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
15e20 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
15e30 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
15e40 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
15e50 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
15e60 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
15e70 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
15e80 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
15e90 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
15ea0 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
15eb0 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
15ec0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e  ERR_BLOCKED].  ^
15ed0 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
15ee0 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
15ef0 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
15f00 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
15f10 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
15f20 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
15f30 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
15f40 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
15f50 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
15f60 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
15f70 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
15f80 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
15f90 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
15fa0 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
15fb0 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
15fc0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
15fd0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
15fe0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
15ff0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
16000 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16010 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
16020 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
16030 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
16040 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
16050 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
16060 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
16070 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
16080 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ut()].** will al
16090 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20  so set or clear 
160a0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
160b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
160c0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
160d0 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
160e0 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
160f0 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
16100 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
16110 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
16120 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e  usy handler.  An
16130 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
16140 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
16150 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
16160 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
16170 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
16180 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
16190 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
161a0 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
161b0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
161c0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
161d0 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ndler..*/.SQLITE
161e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
161f0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
16200 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
16210 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
16220 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16230 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
16240 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  imeout.**.** ^Th
16250 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
16260 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
16270 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
16280 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
16290 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
162a0 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
162b0 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
162c0 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
162d0 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
162e0 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
162f0 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
16300 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
16310 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
16320 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
16330 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
16340 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
16350 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
16360 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
16370 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
16380 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
16390 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
163a0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
163b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
163c0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
163d0 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  OCKED]..**.** ^C
163e0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
163f0 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
16400 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
16410 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
16420 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
16430 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
16440 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
16450 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
16460 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
16470 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
16480 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
16490 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
164a0 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
164b0 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
164c0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
164d0 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
164e0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
164f0 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
16500 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
16510 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
16520 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
16530 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
16540 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ^.*/.SQLITE_API 
16550 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
16560 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
16570 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
16580 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
16590 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
165a0 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
165b0 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
165c0 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
165d0 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
165e0 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
165f0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
16600 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
16610 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
16620 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
16630 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
16640 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
16650 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
16660 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
16670 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
16680 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
16690 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
166a0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
166b0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
166c0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
166d0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
166e0 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
166f0 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
16700 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
16710 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
16720 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
16730 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
16740 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
16750 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
16760 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
16770 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
16780 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
16790 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
167a0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
167b0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
167c0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
167d0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
167e0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
167f0 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
16800 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
16810 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
16820 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
16830 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
16840 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
16850 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
16860 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
16870 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
16880 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
16890 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
168a0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
168b0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
168c0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
168d0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
168e0 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
168f0 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
16900 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
16910 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
16920 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
16930 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
16940 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
16950 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
16960 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
16970 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
16980 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
16990 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
169a0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
169b0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
169c0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
169d0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
169e0 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
169f0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
16a00 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
16a10 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
16a20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
16a30 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
16a40 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
16a50 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
16a60 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
16a70 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
16a80 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
16a90 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
16aa0 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
16ab0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
16ac0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
16ad0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
16ae0 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
16af0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
16b00 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
16b10 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
16b20 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
16b30 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
16b40 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
16b50 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
16b60 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
16b70 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
16b80 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
16b90 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
16ba0 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
16bb0 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
16bc0 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
16bd0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
16be0 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
16bf0 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
16c00 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
16c10 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
16c20 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
16c30 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
16c40 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
16c50 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
16c60 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
16c70 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
16c80 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
16c90 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
16ca0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
16cb0 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
16cc0 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
16cd0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
16ce0 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
16cf0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
16d00 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
16d10 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
16d20 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
16d30 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
16d40 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
16d50 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
16d60 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
16d70 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
16d80 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
16d90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
16da0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
16db0 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
16dc0 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
16dd0 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
16de0 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
16df0 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
16e00 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
16e10 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
16e20 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
16e30 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
16e40 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
16e50 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
16e60 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
16e70 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
16e80 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
16e90 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
16ea0 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
16eb0 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
16ec0 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
16ed0 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
16ee0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
16ef0 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
16f00 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
16f10 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
16f20 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
16f30 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
16f40 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
16f50 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
16f60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
16f70 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
16f80 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
16f90 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
16fa0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
16fb0 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
16fc0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
16fd0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
16fe0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
16ff0 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
17000 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
17010 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
17020 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
17030 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
17040 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
17050 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
17060 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
17070 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
17080 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
17090 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
170a0 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
170b0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
170c0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
170d0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
170e0 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
170f0 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
17100 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
17110 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
17120 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
17130 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
17140 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
17150 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
17160 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
17170 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
17180 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
17190 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
171a0 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
171b0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
171c0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
171d0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
171e0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53  _errmsg()]..*/.S
171f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
17200 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
17210 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
17220 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
17230 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
17240 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
17250 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
17260 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
17270 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
17280 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
17290 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
172a0 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
172b0 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
172c0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
172d0 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
172e0 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
172f0 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
17300 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
17310 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
17320 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
17330 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
17340 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
17350 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
17360 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
17370 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
17380 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
17390 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
173a0 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
173b0 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
173c0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
173d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
173e0 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
173f0 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
17400 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
17410 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
17420 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
17430 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ary..**.** ^The 
17440 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
17450 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
17460 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
17470 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
17480 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
17490 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
174a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
174b0 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
174c0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
174d0 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
174e0 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
174f0 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
17500 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
17510 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
17520 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
17530 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
17540 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
17550 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
17560 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
17570 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
17580 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
17590 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ng..**.** ^(The 
175a0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
175b0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
175c0 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
175d0 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
175e0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
175f0 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
17600 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
17610 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
17620 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
17630 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17640 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
17650 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
17660 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
17670 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
17680 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
17690 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
176a0 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
176b0 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
176c0 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
176d0 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
176e0 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
176f0 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
17700 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
17710 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
17720 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
17730 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
17740 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
17750 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
17760 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
17770 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
17780 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
17790 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
177a0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
177b0 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
177c0 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
177d0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
177e0 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
177f0 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
17800 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
17810 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
17820 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
17830 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
17840 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
17850 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
17860 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
17870 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
17880 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
17890 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
178a0 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
178b0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
178c0 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
178d0 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
178e0 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
178f0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
17900 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
17910 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
17920 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
17930 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
17940 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
17950 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
17960 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
17970 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
17980 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
17990 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
179a0 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
179b0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  acters..**.** ^T
179c0 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  he sqlite3_vsnpr
179d0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
179e0 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73  s a varargs vers
179f0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
17a00 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a  nprintf()..**.**
17a10 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
17a20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
17a30 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
17a40 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
17a50 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
17a60 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
17a70 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
17a80 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
17a90 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
17aa0 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
17ab0 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
17ac0 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
17ad0 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
17ae0 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
17af0 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
17b00 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
17b10 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
17b20 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
17b30 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e  es a null-termin
17b40 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
17b50 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
17b60 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
17b70 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
17b80 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
17b90 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
17ba0 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
17bb0 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
17bc0 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
17bd0 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
17be0 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
17bf0 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
17c00 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
17c10 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
17c20 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
17c30 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
17c40 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
17c50 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
17c60 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
17c70 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
17c80 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
17c90 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
17ca0 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
17cb0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
17cc0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
17cd0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
17ce0 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
17cf0 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
17d00 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
17d10 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
17d20 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
17d30 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
17d40 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
17d50 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
17d60 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
17d70 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
17d80 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
17d90 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
17da0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
17db0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
17dc0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
17dd0 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
17de0 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
17df0 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
17e00 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
17e10 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
17e20 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
17e30 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
17e40 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
17e50 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
17e60 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
17e70 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
17e80 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
17e90 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
17ea0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
17eb0 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
17ec0 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
17ed0 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
17ee0 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
17ef0 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
17f00 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
17f10 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
17f20 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
17f30 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
17f40 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
17f50 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
17f60 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
17f70 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
17f80 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
17f90 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
17fa0 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
17fb0 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
17fc0 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
17fd0 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
17fe0 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
17ff0 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
18000 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
18010 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
18020 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
18030 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
18040 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
18050 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
18060 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
18070 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
18080 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
18090 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
180a0 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
180b0 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
180c0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
180d0 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
180e0 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
180f0 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
18100 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
18110 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
18120 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
18130 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
18140 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
18150 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
18160 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
18170 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
18180 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
18190 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
181a0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
181b0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
181c0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
181d0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
181e0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
181f0 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
18200 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
18210 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
18220 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
18230 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
18240 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
18250 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
18260 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
18270 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
18280 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
18290 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
182a0 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
182b0 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
182c0 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
182d0 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
182e0 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
182f0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
18300 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
18310 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
18320 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  /.SQLITE_API cha
18330 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
18340 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
18350 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
18360 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
18370 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
18380 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51  r*, va_list);.SQ
18390 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
183a0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
183b0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
183c0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c  char*, ...);.SQL
183d0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
183e0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
183f0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
18400 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
18410 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18420 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
18430 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
18440 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
18450 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
18460 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
18470 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
18480 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
18490 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
184a0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
184b0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
184c0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
184d0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
184e0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
184f0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
18500 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
18510 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
18520 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
18530 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
18540 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
18550 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
18560 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
18570 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
18580 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
18590 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
185a0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
185b0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
185c0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
185d0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
185e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
185f0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
18600 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
18610 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
18620 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
18630 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
18640 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
18650 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
18660 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
18670 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
18680 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
18690 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
186a0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
186b0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
186c0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
186d0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
186e0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
186f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
18700 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
18710 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
18720 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
18730 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
18740 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
18750 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
18760 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
18770 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
18780 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
18790 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
187a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
187b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
187c0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
187d0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
187e0 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
187f0 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
18800 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
18810 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
18820 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
18830 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
18840 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
18850 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
18860 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
18870 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
18880 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
18890 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
188a0 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
188b0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
188c0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
188d0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
188e0 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
188f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
18900 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
18910 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
18920 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
18930 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18940 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
18950 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
18960 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
18970 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
18980 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
18990 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
189a0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
189b0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
189c0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
189d0 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
189e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
189f0 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
18a00 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
18a10 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
18a20 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
18a30 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
18a40 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
18a50 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
18a60 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
18a70 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
18a80 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
18a90 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
18aa0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
18ab0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
18ac0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
18ad0 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
18ae0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
18af0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18b00 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
18b10 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
18b20 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
18b30 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
18b40 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
18b50 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
18b60 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
18b70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
18b80 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
18b90 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
18ba0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
18bb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
18bc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
18bd0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
18be0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
18bf0 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
18c00 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
18c10 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
18c20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
18c30 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
18c40 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
18c50 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
18c60 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
18c70 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
18c80 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
18c90 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
18ca0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
18cb0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
18cc0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
18cd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
18ce0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
18cf0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
18d00 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
18d10 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
18d20 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
18d30 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
18d40 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
18d50 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
18d60 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
18d70 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
18d80 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
18d90 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
18da0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
18db0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
18dc0 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
18dd0 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
18de0 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
18df0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
18e00 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
18e10 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
18e20 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
18e30 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
18e40 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
18e50 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
18e60 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
18e70 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
18e80 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
18e90 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
18ea0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
18eb0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
18ec0 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
18ed0 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
18ee0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
18ef0 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
18f00 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
18f10 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
18f20 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57  sed..**.** The W
18f30 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
18f40 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a  ace layer calls.
18f50 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
18f60 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
18f70 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
18f80 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
18f90 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
18fa0 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
18fb0 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
18fc0 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
18fd0 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
18fe0 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
18ff0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
19000 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
19010 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
19020 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
19030 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62   are detected, b
19040 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72  ut.** they are r
19050 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
19060 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
19070 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
19080 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
19090 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
190a0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
190b0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
190c0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
190d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
190e0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
190f0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
19100 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
19110 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
19120 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
19130 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
19140 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
19150 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
19160 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
19170 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
19180 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
19190 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
191a0 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
191b0 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
191c0 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
191d0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
191e0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
191f0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
19200 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
19210 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
19220 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
19230 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d   void *sqlite3_m
19240 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49  alloc(int);.SQLI
19250 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
19260 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
19270 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
19280 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
19290 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
192a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
192b0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
192c0 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
192d0 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
192e0 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
192f0 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
19300 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
19310 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
19320 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
19330 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
19340 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
19350 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
19360 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
19370 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
19380 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
19390 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
193a0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
193b0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
193c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
193d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
193e0 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
193f0 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
19400 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
19410 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
19420 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
19430 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
19440 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
19450 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
19460 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
19470 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
19480 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
19490 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
194a0 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
194b0 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
194c0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
194d0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
194e0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
194f0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
19500 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
19510 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
19520 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
19530 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
19540 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
19550 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
19560 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
19570 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
19580 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
19590 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
195a0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
195b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
195c0 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
195d0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
195e0 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
195f0 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
19600 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
19610 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
19620 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
19630 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
19640 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
19650 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
19660 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
19670 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
19680 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
19690 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
196a0 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
196b0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
196c0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
196d0 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54   reset..*/.SQLIT
196e0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
196f0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
19700 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53  ry_used(void);.S
19710 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
19720 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
19730 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
19740 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
19750 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19760 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
19770 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
19780 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
19790 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
197a0 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
197b0 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
197c0 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
197d0 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
197e0 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
197f0 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
19800 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
19810 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
19820 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
19830 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
19840 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
19850 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
19860 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
19870 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
19880 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
19890 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
198a0 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
198b0 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
198c0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
198d0 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
198e0 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
198f0 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
19900 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
19910 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
19920 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
19930 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
19940 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
19950 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
19960 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
19970 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
19980 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
19990 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
199a0 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
199b0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
199c0 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
199d0 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
199e0 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
199f0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
19a00 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
19a10 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75   ^On all subsequ
19a20 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
19a30 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
19a40 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
19a50 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
19a60 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
19a70 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
19a80 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
19a90 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
19aa0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
19ab0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61   void sqlite3_ra
19ac0 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
19ad0 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
19ae0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
19af0 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
19b00 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
19b10 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
19b20 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
19b30 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19b40 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
19b50 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
19b60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
19b70 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
19b80 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
19b90 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
19ba0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
19bb0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
19bc0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
19bd0 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
19be0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
19bf0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
19c00 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
19c10 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
19c20 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
19c30 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
19c40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
19c50 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
19c60 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
19c70 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
19c80 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
19c90 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
19ca0 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
19cb0 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
19cc0 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
19cd0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
19ce0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
19cf0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
19d00 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
19d10 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
19d20 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
19d30 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
19d40 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
19d50 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
19d60 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
19d70 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
19d80 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
19d90 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
19da0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
19db0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
19dc0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
19dd0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
19de0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
19df0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
19e00 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
19e10 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
19e20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
19e30 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
19e40 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
19e50 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
19e60 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
19e70 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
19e80 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
19e90 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
19ea0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
19eb0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
19ec0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
19ed0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
19ee0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
19ef0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
19f00 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
19f10 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
19f20 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
19f30 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
19f40 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
19f50 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
19f60 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
19f70 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
19f80 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
19f90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
19fa0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
19fb0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
19fc0 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
19fd0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
19fe0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
19ff0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1a000 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1a010 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1a020 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1a030 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1a040 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1a050 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1a060 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1a070 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a080 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1a090 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1a0a0 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1a0b0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1a0c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1a0d0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1a0e0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1a0f0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1a100 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1a110 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1a120 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1a130 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1a140 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1a150 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1a160 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1a170 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1a180 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1a190 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1a1a0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1a1b0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1a1c0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1a1d0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1a1e0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1a1f0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1a200 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1a210 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1a220 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1a230 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1a240 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1a250 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1a260 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1a270 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1a280 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1a290 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1a2a0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1a2b0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1a2c0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1a2d0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1a2e0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1a2f0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1a300 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1a310 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1a320 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1a330 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1a340 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1a350 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1a360 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1a370 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1a380 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1a390 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1a3a0 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1a3b0 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1a3c0 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1a3d0 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1a3e0 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1a3f0 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1a400 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1a410 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1a420 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1a430 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1a440 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1a450 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1a460 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1a470 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1a480 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1a490 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1a4a0 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1a4b0 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1a4c0 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1a4d0 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1a4e0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1a4f0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1a500 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1a510 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1a520 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1a530 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1a540 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1a550 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1a560 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1a570 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1a580 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1a590 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1a5a0 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1a5b0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1a5c0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1a5d0 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1a5e0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1a5f0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1a600 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1a610 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1a620 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1a630 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1a640 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1a650 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1a660 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1a670 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1a680 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1a690 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1a6a0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1a6b0 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1a6c0 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1a6d0 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1a6e0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1a6f0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1a700 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1a710 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1a720 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1a730 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1a740 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1a750 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1a760 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1a770 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1a780 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1a790 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1a7a0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1a7b0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1a7c0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1a7d0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1a7e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a7f0 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1a800 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1a810 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1a820 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1a830 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1a840 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1a850 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1a860 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1a870 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1a880 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1a890 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1a8a0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1a8b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1a8c0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1a8d0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1a8e0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1a8f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1a900 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1a910 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1a920 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1a930 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1a940 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1a950 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1a960 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1a970 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1a980 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1a990 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1a9a0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1a9b0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1a9c0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1a9d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1a9e0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1a9f0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1aa00 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1aa10 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1aa20 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1aa30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1aa40 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1aa50 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1aa60 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1aa70 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1aa80 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1aa90 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1aaa0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1aab0 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1aac0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1aad0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1aae0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1aaf0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ab00 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1ab10 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1ab20 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1ab30 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1ab40 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1ab50 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1ab60 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1ab70 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1ab80 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1ab90 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1aba0 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1abb0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1abc0 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1abd0 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1abe0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1abf0 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1ac00 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1ac10 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1ac20 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
1ac30 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74   int sqlite3_set
1ac40 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1ac50 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1ac60 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1ac70 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1ac80 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1ac90 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1aca0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1acb0 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1acc0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1acd0 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1ace0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1acf0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1ad00 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1ad10 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1ad20 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1ad30 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1ad40 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1ad50 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1ad60 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1ad70 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1ad80 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1ad90 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1ada0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1adb0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1adc0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1add0 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1ade0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1adf0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1ae00 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1ae10 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1ae20 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1ae30 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f  ed as a [SQLITE_
1ae40 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72  ROLLBACK | retur
1ae50 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20  n code].** from 
1ae60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
1ae70 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
1ae80 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
1ae90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1aea0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1aeb0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1aec0 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1aed0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1aee0 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1aef0 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1af00 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1af10 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1af20 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1af30 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1af40 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
1af50 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1af60 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1af70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
1af80 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
1af90 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
1afa0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
1afb0 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
1afc0 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
1afd0 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
1afe0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1aff0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1b000 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1b010 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
1b020 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
1b030 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
1b040 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
1b050 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
1b060 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
1b070 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
1b080 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
1b090 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
1b0a0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
1b0b0 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
1b0c0 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
1b0d0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
1b0e0 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
1b0f0 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
1b100 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1b110 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
1b120 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
1b130 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
1b140 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
1b150 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
1b160 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
1b170 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
1b180 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1b190 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
1b1a0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1b1b0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1b1c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1b1d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1b1e0 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1b1f0 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1b200 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1b210 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
1b220 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1b230 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b240 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1b250 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1b260 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1b270 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1b280 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1b290 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1b2a0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1b2b0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1b2c0 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1b2d0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1b2e0 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
1b2f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b300 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b310 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
1b320 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
1b330 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
1b340 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1b350 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
1b360 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1b370 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1b380 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b390 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1b3a0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
1b3b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1b3c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b3d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b3e0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1b3f0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
1b400 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1b410 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1b420 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b430 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1b440 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
1b450 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1b460 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b470 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b480 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1b490 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
1b4a0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1b4b0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1b4c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b4d0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1b4e0 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
1b4f0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1b500 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b510 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b520 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
1b530 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
1b540 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1b550 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b560 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b570 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
1b580 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
1b590 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1b5a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b5b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b5c0 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
1b5d0 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
1b5e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1b5f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b600 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b610 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
1b620 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
1b630 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1b640 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1b650 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b660 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
1b670 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
1b680 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1b690 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b6a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1b6b0 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
1b6c0 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
1b6d0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1b6e0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1b6f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1b700 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
1b710 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
1b720 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1b730 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b740 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1b750 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1b760 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
1b770 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1b780 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1b790 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1b7a0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
1b7b0 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
1b7c0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1b7d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b7e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1b7f0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
1b800 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
1b810 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1b820 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1b830 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
1b840 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
1b850 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1b860 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b870 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b880 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
1b890 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
1b8a0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1b8b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b8c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b8d0 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
1b8e0 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
1b8f0 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
1b900 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
1b910 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
1b920 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
1b930 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
1b940 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1b950 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1b960 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b970 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
1b980 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
1b990 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1b9a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b9b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b9c0 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
1b9d0 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
1b9e0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1b9f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ba00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ba10 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
1ba20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
1ba30 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ba40 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1ba50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ba60 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
1ba70 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
1ba80 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
1ba90 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1baa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1bab0 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
1bac0 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
1bad0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
1bae0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1baf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bb00 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
1bb10 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
1bb20 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
1bb30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1bb40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1bb50 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
1bb60 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
1bb70 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
1bb80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1bb90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
1bba0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
1bbb0 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
1bbc0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1bbd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1bbe0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1bbf0 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
1bc00 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
1bc10 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1bc20 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1bc30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1bc40 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
1bc50 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
1bc60 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1bc70 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1bc80 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
1bc90 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
1bca0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
1bcb0 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
1bcc0 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
1bcd0 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
1bce0 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
1bcf0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1bd00 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
1bd10 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
1bd20 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
1bd30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1bd40 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
1bd50 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
1bd60 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
1bd70 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
1bd80 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1bd90 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1bda0 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
1bdb0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
1bdc0 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
1bdd0 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
1bde0 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
1bdf0 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
1be00 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
1be10 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1be20 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1be30 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
1be40 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
1be50 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
1be60 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
1be70 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
1be80 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
1be90 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
1bea0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
1beb0 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
1bec0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
1bed0 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
1bee0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
1bef0 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
1bf00 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
1bf10 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
1bf20 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
1bf30 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
1bf40 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
1bf50 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
1bf60 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
1bf70 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
1bf80 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
1bf90 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
1bfa0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
1bfb0 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
1bfc0 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
1bfd0 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
1bfe0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1bff0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1c000 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1c010 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1c020 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1c030 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1c040 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
1c050 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1c060 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
1c070 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1c080 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
1c090 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
1c0a0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
1c0b0 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
1c0c0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
1c0d0 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
1c0e0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
1c0f0 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
1c100 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
1c110 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
1c120 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1c130 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
1c140 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
1c150 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
1c160 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
1c170 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
1c180 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
1c190 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
1c1a0 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
1c1b0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1c1c0 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
1c1d0 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
1c1e0 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
1c1f0 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
1c200 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
1c210 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
1c220 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
1c230 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1c240 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
1c250 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
1c260 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1c270 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
1c280 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1c290 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
1c2a0 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
1c2b0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1c2c0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
1c2d0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
1c2e0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
1c2f0 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
1c300 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
1c310 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
1c320 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
1c330 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
1c340 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1c350 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
1c360 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
1c370 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
1c380 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1c390 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
1c3a0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
1c3b0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
1c3c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
1c3d0 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
1c3e0 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
1c3f0 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
1c400 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
1c410 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
1c420 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
1c430 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1c440 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
1c450 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c460 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
1c470 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
1c480 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
1c490 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
1c4a0 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
1c4b0 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
1c4c0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
1c4d0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
1c4e0 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
1c4f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
1c500 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1c510 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
1c520 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
1c530 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
1c540 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1c550 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
1c560 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
1c570 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
1c580 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
1c590 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
1c5a0 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  ck X..**.** ^Onl
1c5b0 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
1c5c0 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
1c5d0 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
1c5e0 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
1c5f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c600 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
1c610 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
1c620 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
1c630 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
1c640 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
1c650 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
1c660 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
1c670 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
1c680 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1c690 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
1c6a0 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
1c6b0 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
1c6c0 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
1c6d0 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
1c6e0 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
1c6f0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1c700 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
1c710 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
1c720 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
1c730 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
1c740 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
1c750 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
1c760 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
1c770 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
1c780 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1c790 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1c7a0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1c7b0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1c7c0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1c7d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1c7e0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
1c7f0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1c800 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1c810 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1c820 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1c830 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1c840 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1c850 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c860 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1c870 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1c880 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1c890 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ..**.*/.SQLITE_A
1c8a0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
1c8b0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1c8c0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
1c8d0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
1c8e0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1c8f0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
1c900 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
1c910 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
1c920 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1c930 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
1c940 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
1c950 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1c960 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
1c970 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
1c980 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1c990 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1c9a0 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
1c9b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1c9c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1c9d0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
1c9e0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1c9f0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
1ca00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1ca10 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
1ca20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1ca30 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1ca40 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1ca50 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1ca60 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1ca70 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1ca80 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1ca90 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1caa0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1cab0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1cac0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1cad0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1cae0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1caf0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1cb00 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1cb10 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1cb20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
1cb30 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1cb40 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
1cb50 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
1cb60 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
1cb70 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1cb80 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
1cb90 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
1cba0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
1cbb0 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
1cbc0 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
1cbd0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1cbe0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
1cbf0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
1cc00 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
1cc10 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
1cc20 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
1cc30 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
1cc40 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
1cc50 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
1cc60 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
1cc70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1cc80 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
1cc90 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
1cca0 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
1ccb0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1ccc0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
1ccd0 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
1cce0 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
1ccf0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
1cd00 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
1cd10 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
1cd20 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
1cd30 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
1cd40 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
1cd50 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
1cd60 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
1cd70 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1cd80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cd90 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
1cda0 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
1cdb0 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
1cdc0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1cdd0 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
1cde0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
1cdf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1ce00 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
1ce10 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
1ce20 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1ce30 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
1ce40 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
1ce50 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
1ce60 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
1ce70 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
1ce80 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
1ce90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
1cea0 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
1ceb0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
1cec0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1ced0 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
1cee0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
1cef0 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
1cf00 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1cf10 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
1cf20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1cf30 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1cf40 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
1cf50 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1cf60 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
1cf70 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1cf80 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
1cf90 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
1cfa0 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
1cfb0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
1cfc0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1cfd0 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
1cfe0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1cff0 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
1d000 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
1d010 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1d020 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
1d030 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
1d040 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1d050 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1d060 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1d070 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
1d080 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1d090 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1d0a0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1d0b0 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
1d0c0 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
1d0d0 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
1d0e0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
1d0f0 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
1d100 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
1d110 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
1d120 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
1d130 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
1d140 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
1d150 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1d160 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1d170 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1d180 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
1d190 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1d1a0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1d1b0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1d1c0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1d1d0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
1d1e0 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
1d1f0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
1d200 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
1d210 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
1d220 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
1d230 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
1d240 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1d250 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
1d260 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
1d270 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
1d280 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
1d290 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1d2a0 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
1d2b0 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
1d2c0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
1d2d0 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
1d2e0 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
1d2f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1d300 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
1d310 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
1d320 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1d330 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1d340 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1d350 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1d360 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1d370 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
1d380 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d390 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
1d3a0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
1d3b0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
1d3c0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
1d3d0 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
1d3e0 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
1d3f0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1d400 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1d410 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
1d420 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1d430 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
1d440 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
1d450 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d460 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
1d470 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1d480 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
1d490 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
1d4a0 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
1d4b0 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
1d4c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
1d4d0 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
1d4e0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
1d4f0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
1d500 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
1d510 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d520 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
1d530 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
1d540 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
1d550 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1d560 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
1d570 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
1d580 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
1d590 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1d5a0 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
1d5b0 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
1d5c0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1d5d0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1d5e0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1d5f0 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
1d600 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
1d610 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1d620 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
1d630 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
1d640 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
1d650 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1d660 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
1d670 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1d680 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
1d690 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
1d6a0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
1d6b0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1d6c0 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
1d6d0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1d6e0 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
1d6f0 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
1d700 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
1d710 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1d720 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
1d730 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1d740 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
1d750 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1d760 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
1d770 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
1d780 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1d790 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1d7a0 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
1d7b0 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
1d7c0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
1d7d0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
1d7e0 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
1d7f0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1d800 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1d810 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
1d820 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1d830 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
1d840 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
1d850 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
1d860 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
1d870 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
1d880 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
1d890 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
1d8a0 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
1d8b0 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
1d8c0 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
1d8d0 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
1d8e0 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
1d8f0 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
1d900 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
1d910 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
1d920 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
1d930 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
1d940 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1d950 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
1d960 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
1d970 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
1d980 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
1d990 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
1d9a0 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
1d9b0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1d9c0 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
1d9d0 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
1d9e0 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
1d9f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1da00 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
1da10 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
1da20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
1da30 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
1da40 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
1da50 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
1da60 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
1da70 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
1da80 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
1da90 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
1daa0 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
1dab0 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
1dac0 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
1dad0 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
1dae0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
1daf0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
1db00 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
1db10 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
1db20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
1db30 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
1db40 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1db50 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
1db60 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
1db70 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
1db80 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
1db90 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
1dba0 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
1dbb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
1dbc0 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
1dbd0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
1dbe0 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
1dbf0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
1dc00 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
1dc10 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
1dc20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
1dc30 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
1dc40 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
1dc50 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
1dc60 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
1dc70 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
1dc80 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
1dc90 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
1dca0 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
1dcb0 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
1dcc0 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
1dcd0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1dce0 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
1dcf0 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
1dd00 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
1dd10 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
1dd20 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
1dd30 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
1dd40 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
1dd50 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
1dd60 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
1dd70 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
1dd80 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
1dd90 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
1dda0 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
1ddb0 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
1ddc0 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
1ddd0 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
1dde0 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
1ddf0 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
1de00 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
1de10 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
1de20 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
1de30 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
1de40 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
1de50 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
1de60 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
1de70 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
1de80 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
1de90 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
1dea0 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
1deb0 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
1dec0 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
1ded0 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
1dee0 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
1def0 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
1df00 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
1df10 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
1df20 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
1df30 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
1df40 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
1df50 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
1df60 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
1df70 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
1df80 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69  path. .** ^On wi
1df90 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
1dfa0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
1dfb0 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
1dfc0 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
1dfd0 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
1dfe0 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b  . "C:")..**.** [
1dff0 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
1e000 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
1e010 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
1e020 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
1e030 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
1e040 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
1e050 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
1e060 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
1e070 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
1e080 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
1e090 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
1e0a0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  ** SQLite interp
1e0b0 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69  rets the followi
1e0c0 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70  ng three query p
1e0d0 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
1e0e0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
1e0f0 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
1e100 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
1e110 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
1e120 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
1e130 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
1e140 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
1e150 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
1e160 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
1e170 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
1e180 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
1e190 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1e1a0 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
1e1b0 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
1e1c0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
1e1d0 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
1e1e0 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
1e1f0 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
1e200 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
1e210 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
1e220 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
1e230 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
1e240 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
1e250 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
1e260 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
1e270 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
1e280 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
1e290 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
1e2a0 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
1e2b0 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
1e2c0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
1e2d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1e2e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1e2f0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
1e300 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
1e310 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
1e320 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
1e330 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
1e340 6f 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a 20 20  o", "rw" or.**  
1e350 20 20 20 22 72 77 63 22 2e 20 41 74 74 65 6d 70     "rwc". Attemp
1e360 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
1e370 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
1e380 65 20 69 73 20 61 6e 20 65 72 72 6f 72 29 5e 2e  e is an error)^.
1e390 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
1e3a0 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
1e3b0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1e3c0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1e3d0 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
1e3e0 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
1e3f0 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
1e400 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
1e410 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
1e420 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
1e430 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1e440 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  to sqlite3_prepa
1e450 72 65 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  re_v2(). ^If the
1e460 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
1e470 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
1e480 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
1e490 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1e4a0 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
1e4b0 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
1e4c0 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
1e4d0 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
1e4e0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
1e4f0 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
1e500 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
1e510 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
1e520 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
1e530 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
1e540 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
1e550 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
1e560 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
1e570 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
1e580 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
1e590 6e 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20 20 20  n_v2() is .**   
1e5a0 20 20 75 73 65 64 2c 20 69 74 20 69 73 20 61 6e    used, it is an
1e5b0 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66   error to specif
1e5c0 79 20 61 20 76 61 6c 75 65 20 66 6f 72 20 74 68  y a value for th
1e5d0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
1e5e0 20 74 68 61 74 20 69 73 20 0a 2a 2a 20 20 20 20   that is .**    
1e5f0 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
1e600 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
1e610 69 66 69 65 64 20 62 79 20 74 68 65 20 66 6c 61  ified by the fla
1e620 67 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  gs passed as the
1e630 20 74 68 69 72 64 20 0a 2a 2a 20 20 20 20 20 70   third .**     p
1e640 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1e650 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
1e660 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
1e670 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
1e680 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
1e690 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
1e6a0 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
1e6b0 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
1e6c0 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
1e6d0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
1e6e0 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
1e6f0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1e700 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
1e710 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
1e720 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
1e730 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
1e740 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
1e750 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
1e760 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
1e770 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
1e780 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
1e790 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1e7a0 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
1e7b0 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
1e7c0 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
1e7d0 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
1e7e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
1e7f0 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
1e800 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
1e810 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
1e820 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75  des any behaviou
1e830 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
1e840 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
1e850 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1e860 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
1e870 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1e880 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  E flag..** </ul>
1e890 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
1e8a0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
1e8b0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
1e8c0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
1e8d0 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
1e8e0 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
1e8f0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1e900 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
1e910 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
1e920 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
1e930 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
1e940 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
1e950 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
1e960 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
1e970 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
1e980 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
1e990 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
1e9a0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
1e9b0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
1e9c0 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
1e9d0 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
1e9e0 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
1e9f0 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
1ea00 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
1ea10 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
1ea20 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
1ea30 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
1ea40 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
1ea50 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
1ea60 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
1ea70 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
1ea80 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
1ea90 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
1eaa0 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
1eab0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
1eac0 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
1ead0 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
1eae0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
1eaf0 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
1eb00 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
1eb10 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
1eb20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
1eb30 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
1eb40 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
1eb50 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
1eb60 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
1eb70 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
1eb80 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
1eb90 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
1eba0 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
1ebb0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
1ebc0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
1ebd0 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
1ebe0 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
1ebf0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
1ec00 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
1ec10 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
1ec20 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
1ec30 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
1ec40 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
1ec50 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
1ec60 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
1ec70 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
1ec80 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
1ec90 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
1eca0 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
1ecb0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
1ecc0 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
1ecd0 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
1ece0 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
1ecf0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
1ed00 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
1ed10 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
1ed20 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
1ed30 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
1ed40 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
1ed50 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
1ed60 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
1ed70 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
1ed80 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
1ed90 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
1eda0 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
1edb0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
1edc0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1edd0 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
1ede0 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
1edf0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
1ee00 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
1ee10 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
1ee20 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
1ee30 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
1ee40 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63  b?vfs=unix-noloc
1ee50 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  k <td>.**       
1ee60 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
1ee70 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
1ee80 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
1ee90 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c  al VFS "unix-nol
1eea0 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ock"..** <tr><td
1eeb0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
1eec0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
1eed0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
1eee0 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
1eef0 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
1ef00 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
1ef10 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
1ef20 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
1ef30 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
1ef40 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
1ef50 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
1ef60 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
1ef70 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
1ef80 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
1ef90 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
1efa0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
1efb0 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
1efc0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
1efd0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
1efe0 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
1eff0 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
1f000 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
1f010 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
1f020 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
1f030 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
1f040 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
1f050 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
1f060 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
1f070 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
1f080 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
1f090 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
1f0a0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
1f0b0 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
1f0c0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
1f0d0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
1f0e0 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
1f0f0 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
1f100 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
1f110 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
1f120 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
1f130 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
1f140 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
1f150 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
1f160 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
1f170 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
1f180 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
1f190 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1f1a0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
1f1b0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1f1c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
1f1d0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
1f1e0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
1f1f0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
1f200 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
1f210 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
1f220 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
1f230 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
1f240 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
1f250 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
1f260 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
1f270 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
1f280 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
1f290 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 53 51  open_v2()..*/.SQ
1f2a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1f2b0 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
1f2c0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
1f2d0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1f2e0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
1f2f0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
1f300 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
1f310 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
1f320 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
1f330 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1f340 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
1f350 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
1f360 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1f370 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1f380 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
1f390 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
1f3a0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1f3b0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
1f3c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1f3d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1f3e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
1f3f0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1f400 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1f410 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
1f420 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
1f430 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1f440 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1f450 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
1f460 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
1f470 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
1f480 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
1f490 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
1f4a0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
1f4b0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1f4c0 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
1f4d0 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
1f4e0 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eters.**.** This
1f4f0 20 69 73 20 61 20 75 74 69 6c 69 74 79 20 72 6f   is a utility ro
1f500 75 74 69 6e 65 2c 20 75 73 65 66 75 6c 20 74 6f  utine, useful to
1f510 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1f520 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
1f530 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  s.** to see if a
1f540 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
1f550 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
1f560 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
1f570 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
1f580 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
1f590 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
1f5a0 6c 75 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  lue of the query
1f5b0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1f5c0 2a 20 54 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  * The zFilename 
1f5d0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
1f5e0 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
1f5f0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
1f600 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 6d 65 74 68   xOpen().** meth
1f610 6f 64 20 6f 66 20 61 20 56 46 53 20 69 6d 70 6c  od of a VFS impl
1f620 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
1f630 20 7a 50 61 72 61 6d 20 61 72 67 75 6d 65 6e 74   zParam argument
1f640 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1f650 74 68 65 0a 2a 2a 20 71 75 65 72 79 20 70 61 72  the.** query par
1f660 61 6d 65 74 65 72 20 77 65 20 73 65 65 6b 2e 20  ameter we seek. 
1f670 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
1f680 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
1f690 6f 66 20 74 68 65 20 7a 50 61 72 61 6d 0a 2a 2a  of the zParam.**
1f6a0 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74   parameter if it
1f6b0 20 65 78 69 73 74 73 2e 20 20 49 66 20 74 68 65   exists.  If the
1f6c0 20 70 61 72 61 6d 65 74 65 72 20 64 6f 65 73 20   parameter does 
1f6d0 6e 6f 74 20 65 78 69 73 74 2c 20 74 68 69 73 20  not exist, this 
1f6e0 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72  routine.** retur
1f6f0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1f700 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
1f710 7a 46 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65  zFilename argume
1f720 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  nt to this funct
1f730 69 6f 6e 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  ion is not a poi
1f740 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
1f750 0a 2a 2a 20 70 61 73 73 65 64 20 69 6e 74 6f 20  .** passed into 
1f760 74 68 65 20 78 4f 70 65 6e 20 56 46 53 20 6d 65  the xOpen VFS me
1f770 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
1f780 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
1f790 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75 6e  routine.** is un
1f7a0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
1f7b0 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
1f7c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1f7d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1f7e0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
1f7f0 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
1f800 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
1f810 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 0a 0a  har *zParam);...
1f820 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f830 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
1f840 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e  Messages.**.** ^
1f850 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
1f860 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
1f870 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
1f880 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
1f890 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
1f8a0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
1f8b0 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
1f8c0 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
1f8d0 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
1f8e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1f8f0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1f900 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
1f910 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
1f920 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
1f930 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
1f940 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
1f950 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1f960 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
1f970 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
1f980 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71  efined.  ^The sq
1f990 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
1f9a0 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
1f9b0 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
1f9c0 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
1f9d0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
1f9e0 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
1f9f0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
1fa00 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
1fa10 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
1fa20 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
1fa30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1fa40 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
1fa50 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1fa60 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
1fa70 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
1fa80 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
1fa90 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
1faa0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1fab0 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
1fac0 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
1fad0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
1fae0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
1faf0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
1fb00 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
1fb10 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1fb20 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
1fb30 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
1fb40 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
1fb50 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
1fb60 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
1fb70 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
1fb80 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
1fb90 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
1fba0 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
1fbb0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
1fbc0 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
1fbd0 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
1fbe0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1fbf0 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
1fc00 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
1fc10 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
1fc20 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
1fc30 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
1fc40 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
1fc50 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
1fc60 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
1fc70 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
1fc80 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
1fc90 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
1fca0 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
1fcb0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
1fcc0 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
1fcd0 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
1fce0 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
1fcf0 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
1fd00 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
1fd10 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
1fd20 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
1fd30 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
1fd40 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
1fd50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1fd60 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
1fd70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
1fd80 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
1fd90 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
1fda0 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
1fdb0 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
1fdc0 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
1fdd0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
1fde0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
1fdf0 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
1fe00 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
1fe10 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
1fe20 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
1fe30 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
1fe40 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
1fe50 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
1fe60 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
1fe70 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
1fe80 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
1fe90 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
1fea0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
1feb0 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
1fec0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
1fed0 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
1fee0 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
1fef0 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
1ff00 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  I int sqlite3_er
1ff10 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1ff20 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  b);.SQLITE_API i
1ff30 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
1ff40 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
1ff50 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
1ff60 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
1ff70 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
1ff80 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
1ff90 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
1ffa0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1ffb0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
1ffc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1ffd0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
1ffe0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
1fff0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
20000 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
20010 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
20020 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
20030 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
20040 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
20050 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
20060 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
20070 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
20080 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
20090 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
200a0 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
200b0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
200c0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
200d0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
200e0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
200f0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
20100 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
20110 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
20120 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
20130 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
20140 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
20150 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
20160 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
20170 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
20180 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
20190 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
201a0 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
201b0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
201c0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
201d0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
201e0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
201f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20200 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
20210 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
20220 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
20230 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
20240 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
20250 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
20260 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
20270 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
20280 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
20290 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
202a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
202b0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
202c0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
202d0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
202e0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
202f0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
20300 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
20310 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
20320 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
20330 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
20340 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
20350 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
20360 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
20370 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
20380 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
20390 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
203a0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
203b0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
203c0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
203d0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
203e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
203f0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
20400 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20410 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
20420 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
20430 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
20440 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
20450 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
20460 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
20470 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
20480 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
20490 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
204a0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
204b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
204c0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
204d0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
204e0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
204f0 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
20500 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
20510 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
20520 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
20530 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
20540 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
20550 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
20560 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
20570 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
20580 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
20590 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
205a0 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
205b0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
205c0 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
205d0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
205e0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
205f0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
20600 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
20610 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
20620 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
20630 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
20640 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
20650 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
20660 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
20670 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
20680 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
20690 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
206a0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
206b0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
206c0 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
206d0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
206e0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
206f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
20700 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
20710 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
20720 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
20730 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
20740 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
20750 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
20760 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
20770 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
20780 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
20790 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
207a0 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
207b0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
207c0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
207d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
207e0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
207f0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
20800 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
20810 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
20820 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
20830 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
20840 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
20850 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
20860 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
20870 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
20880 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
20890 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
208a0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
208b0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
208c0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
208d0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
208e0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
208f0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
20900 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
20910 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
20920 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
20930 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
20940 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
20950 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
20960 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
20970 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
20980 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
20990 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
209a0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
209b0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
209c0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
209d0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
209e0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
209f0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
20a00 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
20a10 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
20a20 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
20a30 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
20a40 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
20a50 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
20a60 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
20a70 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
20a80 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
20a90 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
20aa0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
20ab0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
20ac0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
20ad0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
20ae0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
20af0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
20b00 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ses..*/.SQLITE_A
20b10 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  PI int sqlite3_l
20b20 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
20b30 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
20b40 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
20b50 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
20b60 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
20b70 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
20b80 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
20b90 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
20ba0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
20bb0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
20bc0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
20bd0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
20be0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
20bf0 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
20c00 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
20c10 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
20c20 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
20c30 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
20c40 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
20c50 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
20c60 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
20c70 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
20c80 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
20c90 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
20ca0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
20cb0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
20cc0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
20cd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
20ce0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
20cf0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
20d00 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
20d10 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
20d20 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
20d30 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
20d40 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
20d50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
20d60 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
20d70 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
20d80 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
20d90 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
20da0 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
20db0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
20dc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
20dd0 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
20de0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
20df0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20e00 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
20e10 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
20e20 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
20e30 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
20e40 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
20e50 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
20e60 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
20e70 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
20e80 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
20e90 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
20ea0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
20eb0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
20ec0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
20ed0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
20ee0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
20ef0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
20f00 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
20f10 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
20f20 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
20f30 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
20f40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
20f50 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
20f60 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
20f70 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
20f80 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
20f90 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
20fa0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
20fb0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
20fc0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
20fd0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
20fe0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
20ff0 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
21000 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
21010 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
21020 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
21030 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
21040 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
21050 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
21060 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
21070 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
21080 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
21090 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
210a0 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
210b0 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
210c0 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
210d0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
210e0 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
210f0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
21100 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
21110 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
21120 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
21130 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
21140 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
21150 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
21160 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
21170 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
21180 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
21190 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
211a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
211b0 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
211c0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
211d0 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
211e0 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
211f0 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
21200 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
21210 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
21220 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
21230 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
21240 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
21250 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
21260 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
21270 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
21280 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
21290 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
212a0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
212b0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
212c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
212d0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
212e0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
212f0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
21300 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
21310 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
21320 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
21330 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
21340 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
21350 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
21360 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
21370 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
21380 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
21390 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
213a0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
213b0 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
213c0 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
213d0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
213e0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
213f0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
21400 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21410 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
21420 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
21430 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
21440 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
21450 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
21460 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
21470 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
21480 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
21490 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
214a0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
214b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
214c0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
214d0 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
214e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
214f0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
21500 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
21510 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
21520 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
21530 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
21540 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
21550 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
21560 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
21570 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
21580 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
21590 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
215a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
215b0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
215c0 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
215d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
215e0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
215f0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
21600 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21610 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
21620 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
21630 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
21640 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
21650 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
21660 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
21670 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
21680 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
21690 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
216a0 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
216b0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
216c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
216d0 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
216e0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
216f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
21700 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
21710 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
21720 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
21730 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
21740 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
21750 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
21760 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
21770 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21780 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
21790 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
217a0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
217b0 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
217c0 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
217d0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
217e0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
217f0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
21800 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
21810 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
21820 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
21830 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
21840 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
21850 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
21860 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
21870 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
21880 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
21890 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
218a0 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
218b0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
218c0 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
218d0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
218e0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
218f0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
21900 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
21910 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
21920 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
21930 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
21940 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
21950 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
21960 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
21970 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
21980 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
21990 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
219a0 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
219b0 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
219c0 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
219d0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
219e0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
219f0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
21a00 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
21a10 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
21a20 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
21a30 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
21a40 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
21a50 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
21a60 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
21a70 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
21a80 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
21a90 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
21aa0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
21ab0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
21ac0 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
21ad0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
21ae0 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a  inator bytes..**
21af0 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
21b00 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
21b10 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
21b20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
21b30 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
21b40 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
21b50 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
21b60 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
21b70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
21b80 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
21b90 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
21ba0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
21bb0 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
21bc0 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
21bd0 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
21be0 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
21bf0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
21c00 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
21c10 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
21c20 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
21c30 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
21c40 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
21c50 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
21c60 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
21c70 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
21c80 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
21c90 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
21ca0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
21cb0 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
21cc0 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
21cd0 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
21ce0 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
21cf0 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
21d00 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
21d10 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
21d20 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
21d30 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
21d40 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
21d50 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
21d60 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
21d70 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
21d80 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
21d90 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
21da0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
21db0 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
21dc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
21dd0 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
21de0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
21df0 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
21e00 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
21e10 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
21e20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
21e30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
21e40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
21e50 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
21e60 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
21e70 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
21e80 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
21e90 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
21ea0 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
21eb0 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
21ec0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
21ed0 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
21ee0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
21ef0 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
21f00 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
21f10 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
21f20 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
21f30 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
21f40 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
21f50 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
21f60 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
21f70 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
21f80 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
21f90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
21fa0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
21fb0 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
21fc0 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
21fd0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
21fe0 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
21ff0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
22000 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
22010 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
22020 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
22030 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
22040 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
22050 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
22060 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
22070 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
22080 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
22090 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
220a0 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f   it again..** </
220b0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
220c0 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
220d0 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
220e0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
220f0 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
22100 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
22110 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
22120 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
22130 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
22140 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
22150 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
22160 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
22170 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
22180 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
22190 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
221a0 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
221b0 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
221c0 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
221d0 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
221e0 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
221f0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
22200 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
22210 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
22220 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
22230 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
22240 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
22250 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
22260 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
22270 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
22280 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
22290 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
222a0 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
222b0 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
222c0 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
222d0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
222e0 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
222f0 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
22300 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
22310 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
22320 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
22330 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
22340 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
22350 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
22360 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
22370 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
22380 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
22390 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
223a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
223b0 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
223c0 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
223d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
223e0 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
223f0 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
22400 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
22410 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
22420 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
22430 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
22440 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
22450 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
22460 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
22470 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
22480 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
22490 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
224a0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
224b0 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
224c0 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
224d0 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
224e0 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
224f0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
22500 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT2] compile-t
22510 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
22520 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a  abled..** the .*
22530 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
22540 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
22550 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
22560 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
22570 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
22580 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
22590 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
225a0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
225b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
225c0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
225d0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
225e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
225f0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
22600 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
22610 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
22620 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
22630 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
22640 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
22650 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
22660 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
22670 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
22680 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
22690 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
226a0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
226b0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
226c0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
226d0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
226e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
226f0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
22700 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
22710 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
22720 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
22730 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
22740 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
22750 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
22760 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
22770 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
22780 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
22790 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
227a0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
227b0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
227c0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
227d0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
227e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
227f0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
22800 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
22810 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
22820 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
22830 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
22840 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
22850 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
22860 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
22870 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
22880 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
22890 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
228a0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
228b0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
228c0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
228d0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
228e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
228f0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
22900 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
22910 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
22920 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
22930 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
22940 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
22950 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
22960 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
22970 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
22980 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
22990 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
229a0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
229b0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
229c0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
229d0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
229e0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
229f0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
22a00 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
22a10 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
22a20 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
22a30 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
22a40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
22a50 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
22a60 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
22a70 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
22a80 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
22a90 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
22aa0 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
22ab0 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  L.**.** ^This in
22ac0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
22ad0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
22ae0 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
22af0 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
22b00 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
22b10 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
22b20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
22b30 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
22b40 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
22b50 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
22b60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22b70 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
22b80 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
22b90 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
22ba0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
22bb0 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
22bc0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
22bd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
22be0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
22bf0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
22c00 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
22c10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
22c20 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
22c30 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
22c40 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
22c50 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
22c60 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
22c70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22c80 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
22c90 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
22ca0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
22cb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
22cc0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
22cd0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
22ce0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
22cf0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
22d00 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
22d10 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
22d20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
22d30 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
22d40 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
22d50 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
22d60 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
22d70 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
22d80 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
22d90 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
22da0 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
22db0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
22dc0 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
22dd0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
22de0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
22df0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
22e00 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
22e10 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
22e20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
22e30 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
22e40 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
22e50 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
22e60 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
22e70 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
22e80 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
22e90 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
22ea0 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
22eb0 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
22ec0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
22ed0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
22ee0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
22ef0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
22f00 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
22f10 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
22f20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
22f30 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
22f40 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
22f50 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
22f60 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
22f70 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
22f80 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
22f90 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
22fa0 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
22fb0 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
22fc0 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
22fd0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
22fe0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
22ff0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
23000 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
23010 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
23020 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
23030 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
23040 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
23050 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
23060 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
23070 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
23080 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
23090 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
230a0 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
230b0 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
230c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
230d0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
230e0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
230f0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
23100 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
23110 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53  es on disk..*/.S
23120 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
23130 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
23140 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
23150 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
23160 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
23170 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
23180 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
23190 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
231a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
231b0 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
231c0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
231d0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
231e0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
231f0 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
23200 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
23210 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
23220 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
23230 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
23240 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
23250 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
23260 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
23270 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
23280 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
23290 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
232a0 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
232b0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
232c0 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
232d0 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
232e0 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
232f0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
23300 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
23310 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
23320 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
23330 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
23340 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
23350 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
23360 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
23370 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
23380 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
23390 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
233a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
233b0 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
233c0 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
233d0 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
233e0 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
233f0 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
23400 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
23410 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
23420 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
23430 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
23440 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
23450 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
23460 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
23470 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
23480 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
23490 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
234a0 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
234b0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
234c0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
234d0 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
234e0 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
234f0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
23500 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
23510 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
23520 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
23530 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
23540 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
23550 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
23560 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
23570 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
23580 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
23590 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
235a0 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
235b0 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
235c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
235d0 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
235e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
235f0 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
23600 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
23610 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
23620 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
23630 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
23640 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
23650 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
23660 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
23670 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
23680 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
23690 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
236a0 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
236b0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
236c0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
236d0 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
236e0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
236f0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
23700 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
23710 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
23720 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
23730 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
23740 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
23750 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
23760 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
23770 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
23780 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
23790 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
237a0 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
237b0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
237c0 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
237d0 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
237e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
237f0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
23800 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23810 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
23820 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
23830 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
23840 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
23850 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
23860 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
23870 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
23880 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
23890 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
238a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
238b0 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
238c0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
238d0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
238e0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
238f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
23900 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
23910 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
23920 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
23930 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
23940 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
23950 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
23960 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
23970 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
23980 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
23990 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
239a0 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
239b0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
239c0 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
239d0 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
239e0 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
239f0 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
23a00 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
23a10 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
23a20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
23a30 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
23a40 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
23a50 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
23a60 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
23a70 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
23a80 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
23a90 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
23aa0 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
23ab0 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
23ac0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
23ad0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
23ae0 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
23af0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
23b00 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
23b10 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
23b20 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
23b30 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
23b40 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
23b50 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
23b60 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
23b70 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
23b80 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
23b90 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
23ba0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
23bb0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
23bc0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
23bd0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
23be0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
23bf0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
23c00 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
23c10 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
23c20 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
23c30 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
23c40 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e  binding}.**.** ^
23c50 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
23c60 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
23c70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
23c80 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
23c90 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
23ca0 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
23cb0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
23cc0 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
23cd0 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
23ce0 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
23cf0 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
23d00 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
23d10 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
23d20 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
23d30 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
23d40 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
23d50 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
23d60 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
23d70 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
23d80 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
23d90 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
23da0 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
23db0 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
23dc0 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
23dd0 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
23de0 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
23df0 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
23e00 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
23e10 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
23e20 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
23e30 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
23e40 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
23e50 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
23e60 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
23e70 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
23e80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
23e90 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
23ea0 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
23eb0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
23ec0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
23ed0 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
23ee0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
23ef0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
23f00 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
23f10 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
23f20 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
23f30 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
23f40 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
23f50 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
23f60 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
23f70 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
23f80 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
23f90 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
23fa0 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
23fb0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
23fc0 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
23fd0 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
23fe0 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
23ff0 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
24000 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
24010 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
24020 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
24030 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
24040 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
24050 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
24060 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
24070 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
24080 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
24090 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
240a0 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
240b0 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
240c0 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
240d0 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
240e0 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
240f0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
24100 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
24110 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
24120 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
24130 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
24140 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
24150 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
24160 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
24170 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
24180 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
24190 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
241a0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
241b0 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
241c0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
241d0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
241e0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
241f0 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
24200 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
24210 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
24220 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
24230 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
24240 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
24250 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
24260 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
24270 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  s negative, the 
24280 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
24290 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
242a0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
242b0 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
242c0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
242d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
242e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
242f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
24300 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
24310 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
24320 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
24330 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
24340 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
24350 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
24360 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
24370 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
24380 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
24390 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
243a0 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
243b0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
243c0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
243d0 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
243e0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
243f0 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  blob(),.** sqlit
24400 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
24410 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
24420 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20  text16() fails. 
24430 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66   .** ^If the fif
24440 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
24450 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
24460 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
24470 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
24480 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
24490 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
244a0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
244b0 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
244c0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
244d0 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
244e0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
244f0 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
24500 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
24510 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
24520 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
24530 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
24540 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
24550 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
24560 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
24570 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
24580 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
24590 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
245a0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
245b0 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
245c0 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
245d0 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
245e0 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
245f0 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
24600 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
24610 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
24620 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
24630 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
24640 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
24650 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
24660 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
24670 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
24680 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
24690 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
246a0 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
246b0 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
246c0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
246d0 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
246e0 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
246f0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
24700 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
24710 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
24720 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
24730 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
24740 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
24750 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
24760 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
24770 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
24780 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
24790 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
247a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
247b0 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
247c0 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
247d0 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
247e0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
247f0 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
24800 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
24810 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
24820 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
24830 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
24840 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
24850 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
24860 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
24870 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
24880 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24890 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
248a0 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
248b0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
248c0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
248d0 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
248e0 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
248f0 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
24900 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
24910 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
24920 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
24930 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
24940 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
24950 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
24960 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
24970 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
24980 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
24990 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
249a0 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
249b0 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
249c0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
249d0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
249e0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
249f0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
24a00 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
24a10 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
24a20 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
24a30 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
24a40 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
24a50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
24a60 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
24a70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
24a80 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
24a90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
24aa0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
24ab0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
24ac0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
24ad0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
24ae0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
24af0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
24b00 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
24b10 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
24b20 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
24b30 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
24b40 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53   int, double);.S
24b50 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
24b60 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
24b70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24b80 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t, int);.SQLITE_
24b90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
24ba0 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
24bb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
24bc0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53  qlite3_int64);.S
24bd0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
24be0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
24bf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
24c00 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
24c10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
24c20 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
24c30 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
24c40 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
24c50 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
24c60 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
24c70 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
24c80 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
24c90 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
24ca0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
24cb0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
24cc0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
24cd0 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
24ce0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
24cf0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
24d00 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
24d10 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
24d20 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
24d30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
24d40 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
24d50 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
24d60 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
24d70 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
24d80 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
24d90 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
24da0 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
24db0 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
24dc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24dd0 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
24de0 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
24df0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
24e00 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
24e10 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
24e20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
24e30 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
24e40 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
24e50 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
24e60 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
24e70 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
24e80 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
24e90 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
24ea0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
24eb0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
24ec0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
24ed0 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
24ee0 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
24ef0 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
24f00 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
24f10 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
24f20 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
24f30 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
24f40 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
24f50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
24f60 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
24f70 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
24f80 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
24f90 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
24fa0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
24fb0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
24fc0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
24fd0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
24fe0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
24ff0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
25000 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25010 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
25020 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
25030 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25040 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
25050 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
25060 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
25070 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
25080 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
25090 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
250a0 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
250b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
250c0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
250d0 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
250e0 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
250f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25100 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
25110 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
25120 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
25130 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
25140 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
25150 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
25160 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
25170 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
25180 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
25190 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
251a0 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
251b0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
251c0 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
251d0 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
251e0 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
251f0 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
25200 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
25210 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
25220 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
25230 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
25240 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
25250 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
25260 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
25270 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
25280 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
25290 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
252a0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
252b0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
252c0 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
252d0 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
252e0 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
252f0 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
25300 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
25310 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
25320 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
25330 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
25340 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
25350 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
25360 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
25370 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
25380 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
25390 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
253a0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
253b0 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
253c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
253d0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
253e0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
253f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
25400 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
25410 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
25420 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
25430 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
25440 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
25450 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
25460 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
25470 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
25480 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
25490 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
254a0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
254b0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
254c0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
254d0 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
254e0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
254f0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
25500 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
25510 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
25520 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
25530 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
25540 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
25550 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
25560 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
25570 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
25580 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
25590 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
255a0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
255b0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
255c0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
255d0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
255e0 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
255f0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
25600 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
25610 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
25620 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
25630 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
25640 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25650 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
25660 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
25670 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
25680 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
25690 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
256a0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
256b0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
256c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
256d0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
256e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
256f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
25700 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
25710 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
25720 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
25730 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25740 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
25750 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
25760 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
25770 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
25780 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
25790 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
257a0 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
257b0 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
257c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
257d0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
257e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
257f0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
25800 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
25810 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
25820 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
25830 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
25840 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
25850 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
25860 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
25870 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
25880 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
25890 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
258a0 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
258b0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
258c0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
258d0 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
258e0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
258f0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
25900 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
25910 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
25920 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
25930 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
25940 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
25950 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
25960 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
25970 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
25980 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
25990 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
259a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
259b0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
259c0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
259d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
259e0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
259f0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
25a00 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
25a10 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
25a20 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
25a30 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
25a40 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
25a50 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
25a60 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
25a70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
25a80 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
25a90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25aa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
25ab0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
25ac0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
25ad0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
25ae0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
25af0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
25b00 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
25b10 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
25b20 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
25b30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
25b40 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25b50 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
25b60 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
25b70 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
25b80 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
25b90 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
25ba0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
25bb0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
25bc0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
25bd0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
25be0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
25bf0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
25c00 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
25c10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25c20 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
25c30 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
25c40 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
25c50 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
25c60 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
25c70 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
25c80 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
25c90 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
25ca0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
25cb0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
25cc0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
25cd0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
25ce0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
25cf0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
25d00 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
25d10 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
25d20 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
25d30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
25d40 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
25d50 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
25d60 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
25d70 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
25d80 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
25d90 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
25da0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
25db0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
25dc0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
25dd0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
25de0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
25df0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
25e00 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
25e10 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
25e20 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
25e30 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
25e40 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
25e50 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
25e60 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
25e70 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
25e80 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
25e90 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
25ea0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
25eb0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
25ec0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
25ed0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
25ee0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
25ef0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
25f00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
25f10 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
25f20 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
25f30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
25f40 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
25f50 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
25f60 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
25f70 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
25f80 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
25f90 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
25fa0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
25fb0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
25fc0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
25fd0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
25fe0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
25ff0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
26000 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
26010 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
26020 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
26030 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
26040 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
26050 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
26060 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
26070 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
26080 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
26090 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
260a0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
260b0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
260c0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
260d0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
260e0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
260f0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
26100 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
26110 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
26120 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
26130 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
26140 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
26150 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
26160 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
26170 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
26180 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
26190 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
261a0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
261b0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
261c0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
261d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
261e0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
261f0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
26200 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
26210 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
26220 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
26230 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
26240 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
26250 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
26260 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
26270 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
26280 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
26290 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
262a0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
262b0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
262c0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
262d0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
262e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
262f0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
26300 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
26310 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
26320 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
26330 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
26340 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
26350 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
26360 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
26370 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
26380 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
26390 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
263a0 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
263b0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
263c0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
263d0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
263e0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
263f0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
26400 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
26410 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
26420 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
26430 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
26440 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
26450 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
26460 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
26470 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
26480 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
26490 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
264a0 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
264b0 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
264c0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
264d0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
264e0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
264f0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
26500 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
26510 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
26520 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
26530 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
26540 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
26550 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
26560 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
26570 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
26580 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
26590 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
265a0 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
265b0 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
265c0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
265d0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
265e0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
265f0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
26600 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
26610 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
26620 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
26630 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
26640 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
26650 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
26660 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
26670 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
26680 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
26690 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
266a0 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
266b0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
266c0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
266d0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
266e0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
266f0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
26700 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
26710 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
26720 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
26730 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
26740 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
26750 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
26760 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
26770 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
26780 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
26790 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
267a0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
267b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
267c0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
267d0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
267e0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
267f0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
26800 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
26810 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
26820 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
26830 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
26840 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
26850 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
26860 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
26870 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
26880 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
26890 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
268a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
268b0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
268c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
268d0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
268e0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
268f0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
26900 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
26910 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
26920 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
26930 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
26940 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
26950 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
26960 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
26970 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
26980 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
26990 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
269a0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
269b0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
269c0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
269d0 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
269e0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
269f0 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
26a00 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
26a10 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
26a20 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
26a30 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
26a40 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
26a50 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
26a60 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
26a70 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
26a80 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
26a90 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
26aa0 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
26ab0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
26ac0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
26ad0 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
26ae0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
26af0 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
26b00 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
26b10 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
26b20 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
26b30 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
26b40 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
26b50 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
26b60 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
26b70 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
26b80 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
26b90 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
26ba0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
26bb0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
26bc0 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
26bd0 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
26be0 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
26bf0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
26c00 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
26c10 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
26c20 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
26c30 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
26c40 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
26c50 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
26c60 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
26c70 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
26c80 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
26c90 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
26ca0 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
26cb0 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
26cc0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
26cd0 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
26ce0 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
26cf0 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
26d00 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
26d10 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
26d20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
26d30 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
26d40 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
26d50 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
26d60 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
26d70 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
26d80 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
26d90 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
26da0 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
26db0 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
26dc0 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
26dd0 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
26de0 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c  e values..*/.SQL
26df0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
26e00 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
26e10 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
26e20 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
26e30 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
26e40 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
26e50 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
26e60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
26e70 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
26e80 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
26e90 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
26ea0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
26eb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26ec0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
26ed0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
26ee0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
26ef0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
26f00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26f10 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
26f20 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
26f30 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
26f40 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
26f50 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
26f60 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
26f70 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
26f80 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
26f90 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
26fa0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
26fb0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
26fc0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
26fd0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
26fe0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
26ff0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
27000 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
27010 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
27020 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
27030 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
27040 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
27050 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
27060 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
27070 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
27080 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
27090 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
270a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
270b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
270c0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
270d0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
270e0 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
270f0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
27100 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
27110 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
27120 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
27130 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
27140 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
27150 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
27160 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
27170 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
27180 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
27190 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
271a0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
271b0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
271c0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
271d0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
271e0 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
271f0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
27200 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
27210 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
27220 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
27230 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
27240 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
27250 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
27260 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
27270 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
27280 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
27290 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
272a0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
272b0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
272c0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
272d0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
272e0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
272f0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
27300 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
27310 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
27320 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
27330 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
27340 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
27350 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
27360 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
27370 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
27380 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
27390 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
273a0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
273b0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
273c0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
273d0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
273e0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
273f0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
27400 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
27410 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
27420 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
27430 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
27440 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
27450 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
27460 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
27470 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
27480 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
27490 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
274a0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
274b0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
274c0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
274d0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
274e0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
274f0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
27500 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
27510 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
27520 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
27530 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
27540 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
27550 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
27560 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
27570 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
27580 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
27590 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
275a0 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
275b0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
275c0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
275d0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
275e0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
275f0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
27600 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
27610 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
27620 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
27630 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
27640 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
27650 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
27660 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
27670 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
27680 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
27690 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
276a0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
276b0 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
276c0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
276d0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
276e0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
276f0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
27700 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
27710 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
27720 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
27730 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
27740 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
27750 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
27760 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
27770 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
27780 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
27790 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
277a0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
277b0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
277c0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
277d0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
277e0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
277f0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
27800 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
27810 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
27820 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
27830 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
27840 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
27850 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
27860 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
27870 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
27880 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
27890 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
278a0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
278b0 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
278c0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
278d0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
278e0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
278f0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
27900 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
27910 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
27920 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
27930 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
27940 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
27950 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
27960 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
27970 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
27980 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
27990 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
279a0 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
279b0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
279c0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
279d0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
279e0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
279f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27a00 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
27a10 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
27a20 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
27a30 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
27a40 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
27a50 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
27a60 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
27a70 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
27a80 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
27a90 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
27aa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
27ab0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
27ac0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
27ad0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
27ae0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
27af0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
27b00 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
27b10 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
27b20 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
27b30 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
27b40 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
27b50 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
27b60 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
27b70 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
27b80 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
27b90 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
27ba0 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
27bb0 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
27bc0 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
27bd0 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
27be0 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
27bf0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
27c00 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
27c10 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
27c20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
27c30 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
27c40 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
27c50 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
27c60 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
27c70 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
27c80 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
27c90 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
27ca0 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
27cb0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
27cc0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
27cd0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
27ce0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
27cf0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
27d00 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
27d10 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
27d20 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
27d30 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
27d40 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
27d50 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
27d60 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
27d70 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
27d80 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
27d90 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
27da0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
27db0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
27dc0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
27dd0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
27de0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
27df0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
27e00 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
27e10 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
27e20 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
27e30 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
27e40 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
27e50 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
27e60 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
27e70 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
27e80 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
27e90 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
27ea0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
27eb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
27ec0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
27ed0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
27ee0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
27ef0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
27f00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
27f10 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
27f20 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
27f30 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
27f40 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
27f50 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
27f60 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
27f70 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
27f80 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
27f90 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
27fa0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
27fb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
27fc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
27fd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27fe0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
27ff0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
28000 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
28010 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
28020 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
28030 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
28040 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
28050 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
28060 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
28070 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
28080 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
28090 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
280a0 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
280b0 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
280c0 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
280d0 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
280e0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
280f0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
28100 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
28110 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
28120 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
28130 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
28140 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
28150 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
28160 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
28170 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
28180 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
28190 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  nter..**.** See 
281a0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
281b0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
281c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
281d0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
281e0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
281f0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
28200 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
28210 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
28220 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
28230 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
28240 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
28250 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
28260 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
28270 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
28280 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
28290 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
282a0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
282b0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
282c0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
282d0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
282e0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
282f0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
28300 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
28310 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
28320 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
28330 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
28340 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
28350 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
28360 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
28370 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
28380 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
28390 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
283a0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
283b0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
283c0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
283d0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
283e0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
283f0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
28400 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
28410 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
28420 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
28430 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
28440 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
28450 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
28460 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
28470 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
28480 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
28490 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
284a0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
284b0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
284c0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
284d0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
284e0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
284f0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
28500 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28510 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
28520 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
28530 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
28540 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
28550 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
28560 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
28570 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
28580 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
28590 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
285a0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
285b0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
285c0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
285d0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
285e0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
285f0 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
28600 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
28610 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
28620 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
28630 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
28640 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
28650 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
28660 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
28670 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
28680 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
28690 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
286a0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
286b0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
286c0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
286d0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
286e0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
286f0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
28700 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
28710 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
28720 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
28730 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
28740 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
28750 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
28760 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
28770 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
28780 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
28790 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
287a0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
287b0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
287c0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
287d0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
287e0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
287f0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
28800 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
28810 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
28820 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
28830 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
28840 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
28850 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
28860 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
28870 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
28880 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
28890 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
288a0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
288b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
288c0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
288d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
288e0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
288f0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
28900 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
28910 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
28920 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
28930 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
28940 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
28950 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
28960 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
28970 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
28980 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
28990 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
289a0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
289b0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
289c0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
289d0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
289e0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
289f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28a00 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
28a10 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
28a20 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
28a30 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
28a40 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
28a50 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
28a60 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
28a70 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
28a80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28a90 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
28aa0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
28ab0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
28ac0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
28ad0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
28ae0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
28af0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
28b00 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
28b10 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
28b20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
28b30 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
28b40 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
28b50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
28b60 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
28b70 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
28b80 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
28b90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
28ba0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
28bb0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
28bc0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
28bd0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
28be0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
28bf0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
28c00 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
28c10 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
28c20 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
28c30 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
28c40 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
28c50 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
28c60 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
28c70 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
28c80 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
28c90 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
28ca0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
28cb0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
28cc0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
28cd0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
28ce0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
28cf0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
28d00 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
28d10 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
28d20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
28d30 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
28d40 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
28d50 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
28d60 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
28d70 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
28d80 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
28d90 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
28da0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
28db0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
28dc0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
28dd0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
28de0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
28df0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
28e00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
28e10 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
28e20 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
28e30 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
28e40 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
28e50 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
28e60 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
28e70 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
28e80 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
28e90 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
28ea0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
28eb0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
28ec0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
28ed0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
28ee0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
28ef0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
28f00 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
28f10 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
28f20 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
28f30 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
28f40 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
28f50 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
28f60 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
28f70 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
28f80 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
28f90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
28fa0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
28fb0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
28fc0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
28fd0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
28fe0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
28ff0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
29000 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
29010 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
29020 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
29030 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
29040 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
29050 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
29060 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
29070 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
29080 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
29090 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
290a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
290b0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
290c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
290d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
290e0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
290f0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
29100 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
29110 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
29120 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
29130 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
29140 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
29150 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
29160 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
29170 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
29180 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
29190 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
291a0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
291b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
291c0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
291d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
291e0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
291f0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
29200 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
29210 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
29220 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
29230 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
29240 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
29250 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
29260 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
29270 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
29280 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
29290 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
292a0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e  zero terminated.
292b0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
292c0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
292d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
292e0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
292f0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
29300 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
29310 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  * ^The object re
29320 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
29330 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
29340 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
29350 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29360 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
29370 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
29380 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29390 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
293a0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
293b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
293c0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
293d0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
293e0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
293f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29400 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
29410 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
29420 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
29430 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
29440 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
29450 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
29460 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
29470 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
29480 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
29490 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
294a0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
294b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
294c0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
294d0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
294e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
294f0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
29500 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
29510 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
29520 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
29530 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
29540 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
29550 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
29560 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
29570 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
29580 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
29590 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
295a0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
295b0 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
295c0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
295d0 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
295e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
295f0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
29600 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
29610 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
29620 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
29630 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
29640 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
29650 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
29660 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
29670 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
29680 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
29690 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
296a0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
296b0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
296c0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
296d0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
296e0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
296f0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
29700 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
29710 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
29720 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
29730 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
29740 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
29750 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
29760 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
29770 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
29780 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
29790 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
297a0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
297b0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
297c0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
297d0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
297e0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
297f0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
29800 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
29810 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
29820 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
29830 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
29840 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
29850 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
29860 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
29870 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  > Convert from f
29880 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a  loat to integer.
29890 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
298a0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
298b0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
298c0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
298d0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
298e0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
298f0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
29900 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45  ame as FLOAT->TE
29910 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
29920 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
29930 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20  EGER   <td> Use 
29940 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
29950 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
29960 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
29970 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  Use atof().** <t
29980 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
29990 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
299a0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
299b0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
299c0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
299d0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
299e0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
299f0 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
29a00 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
29a10 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
29a20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
29a30 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a  then use atof().
29a40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
29a50 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
29a60 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
29a70 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
29a80 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
29a90 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
29aa0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  uote>)^.**.** Th
29ab0 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
29ac0 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
29ad0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
29ae0 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
29af0 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
29b00 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
29b10 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
29b20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
29b30 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
29b40 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
29b50 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
29b60 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
29b70 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
29b80 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
29b90 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
29ba0 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
29bb0 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
29bc0 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
29bd0 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
29be0 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
29bf0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
29c00 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
29c10 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
29c20 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
29c30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29c40 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
29c50 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
29c60 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
29c70 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
29c80 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
29c90 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
29ca0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
29cb0 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
29cc0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
29cd0 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
29ce0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
29cf0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
29d00 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
29d10 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
29d20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29d30 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
29d40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29d50 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
29d60 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
29d70 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
29d80 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
29d90 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
29da0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
29db0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
29dc0 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
29dd0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
29de0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
29df0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
29e00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
29e10 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
29e20 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
29e30 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
29e40 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
29e50 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
29e60 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
29e70 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
29e80 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
29e90 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
29ea0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
29eb0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
29ec0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
29ed0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
29ee0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
29ef0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
29f00 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
29f10 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
29f20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
29f30 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
29f40 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
29f50 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
29f60 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
29f70 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
29f80 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
29f90 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
29fa0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
29fb0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
29fc0 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
29fd0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
29fe0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
29ff0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
2a000 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
2a010 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
2a020 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
2a030 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
2a040 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
2a050 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
2a060 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
2a070 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
2a080 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
2a090 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
2a0a0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
2a0b0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
2a0c0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2a0d0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
2a0e0 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
2a0f0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
2a100 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2a110 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
2a120 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2a130 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2a140 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2a150 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
2a160 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2a170 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2a180 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2a190 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a1a0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
2a1b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a1c0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
2a1d0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2a1e0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
2a1f0 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
2a200 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2a210 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
2a220 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
2a230 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2a240 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
2a250 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
2a260 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
2a270 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
2a280 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
2a290 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2a2a0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2a2b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2a2c0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
2a2d0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
2a2e0 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
2a2f0 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
2a300 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2a310 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2a320 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
2a330 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2a340 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2a350 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
2a360 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
2a370 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2a380 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
2a390 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2a3a0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
2a3b0 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
2a3c0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
2a3d0 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
2a3e0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
2a3f0 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
2a400 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
2a410 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
2a420 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2a430 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2a440 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a450 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
2a460 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
2a470 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
2a480 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
2a490 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
2a4a0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
2a4b0 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
2a4c0 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
2a4d0 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
2a4e0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
2a4f0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
2a500 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
2a510 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
2a520 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
2a530 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
2a540 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
2a550 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
2a560 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
2a570 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
2a580 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
2a590 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
2a5a0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
2a5b0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
2a5c0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
2a5d0 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
2a5e0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
2a5f0 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
2a600 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
2a610 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
2a620 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2a630 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
2a640 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
2a650 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
2a660 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2a670 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2a680 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2a690 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2a6a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2a6b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2a6c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a6d0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2a6e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2a6f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2a700 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a710 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2a720 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69  _API double sqli
2a730 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
2a740 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2a750 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2a760 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2a770 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
2a780 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a790 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2a7a0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
2a7b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a7c0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2a7d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a7e0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2a7f0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2a800 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a810 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2a820 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2a830 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2a840 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2a850 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
2a860 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2a870 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2a880 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2a890 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2a8a0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2a8b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
2a8c0 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
2a8d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2a8e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a8f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
2a900 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
2a910 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
2a920 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
2a930 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a940 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
2a950 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
2a960 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
2a970 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a980 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
2a990 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
2a9a0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
2a9b0 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
2a9c0 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
2a9d0 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
2a9e0 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
2a9f0 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
2aa00 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2aa10 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
2aa20 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
2aa30 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
2aa40 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
2aa50 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
2aa60 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
2aa70 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
2aa80 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
2aa90 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2aaa0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2aab0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
2aac0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2aad0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
2aae0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
2aaf0 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
2ab00 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
2ab10 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
2ab20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ab30 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
2ab40 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
2ab50 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
2ab60 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
2ab70 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
2ab80 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
2ab90 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
2aba0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
2abb0 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
2abc0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
2abd0 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
2abe0 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
2abf0 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
2ac00 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
2ac10 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ac20 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
2ac30 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
2ac40 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
2ac50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
2ac60 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
2ac70 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
2ac80 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
2ac90 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
2aca0 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
2acb0 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
2acc0 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
2acd0 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
2ace0 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
2acf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
2ad00 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
2ad10 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
2ad20 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
2ad30 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2ad40 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
2ad50 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
2ad60 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
2ad70 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
2ad80 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
2ad90 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
2ada0 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
2adb0 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ption..*/.SQLITE
2adc0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2add0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
2ade0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2adf0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ae00 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
2ae10 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2ae20 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
2ae30 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
2ae40 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
2ae50 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
2ae60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2ae70 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
2ae80 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2ae90 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
2aea0 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
2aeb0 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
2aec0 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
2aed0 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
2aee0 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
2aef0 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
2af00 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
2af10 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
2af20 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
2af30 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
2af40 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
2af50 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
2af60 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
2af70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
2af80 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2af90 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
2afa0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2afb0 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
2afc0 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
2afd0 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
2afe0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
2aff0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2b000 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2b010 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2b020 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2b030 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
2b040 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2b050 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2b060 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
2b070 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
2b080 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
2b090 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
2b0a0 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
2b0b0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2b0c0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
2b0d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
2b0e0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2b0f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2b100 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2b110 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b120 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
2b130 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
2b140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2b150 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
2b160 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2b170 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2b180 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
2b190 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2b1a0 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
2b1b0 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
2b1c0 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
2b1d0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
2b1e0 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
2b1f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b200 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50   S..*/.SQLITE_AP
2b210 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  I int sqlite3_re
2b220 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
2b230 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2b240 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
2b250 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
2b260 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
2b270 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
2b280 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2b290 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
2b2a0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2b2b0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2b2c0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
2b2d0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2b2e0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2b2f0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
2b300 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
2b310 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
2b320 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
2b330 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2b340 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
2b350 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
2b360 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2b370 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
2b380 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2b390 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
2b3a0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2b3b0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
2b3c0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
2b3d0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
2b3e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
2b3f0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
2b400 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
2b410 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2b420 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
2b430 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
2b440 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
2b450 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
2b460 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
2b470 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
2b480 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
2b490 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2b4a0 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
2b4b0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2b4c0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
2b4d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b4e0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
2b4f0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
2b500 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
2b510 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
2b520 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
2b530 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
2b540 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
2b550 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
2b560 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2b570 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
2b580 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
2b590 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b5a0 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
2b5b0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2b5c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b5d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
2b5e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2b5f0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
2b600 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
2b610 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
2b620 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
2b630 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
2b640 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
2b650 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
2b660 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
2b670 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
2b680 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
2b690 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
2b6a0 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
2b6b0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
2b6c0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
2b6d0 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
2b6e0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
2b6f0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
2b700 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
2b710 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
2b720 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
2b730 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
2b740 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2b750 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
2b760 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2b770 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
2b780 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
2b790 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2b7a0 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
2b7b0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
2b7c0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
2b7d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2b7e0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
2b7f0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
2b800 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
2b810 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
2b820 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
2b830 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2b840 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2b850 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
2b860 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
2b870 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
2b880 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
2b890 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
2b8a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2b8b0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2b8c0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
2b8d0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
2b8e0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
2b8f0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
2b900 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
2b910 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
2b920 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
2b930 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
2b940 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51  eters.  Every SQ
2b950 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
2b960 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62  mentation must b
2b970 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
2b980 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  * with UTF-8, UT
2b990 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
2b9a0 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
2b9b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
2b9c0 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
2b9d0 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
2b9e0 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
2b9f0 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70  nother.  ^An app
2ba00 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20  lication may.** 
2ba10 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2ba20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2ba30 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
2ba40 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
2ba50 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
2ba60 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2ba70 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
2ba80 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
2ba90 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
2baa0 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
2bab0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2bac0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2bad0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
2bae0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
2baf0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
2bb00 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
2bb10 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
2bb20 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
2bb30 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
2bb40 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
2bb50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2bb60 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
2bb70 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
2bb80 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
2bb90 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
2bba0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
2bbb0 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
2bbc0 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  NY]..**.** ^(The
2bbd0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2bbe0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
2bbf0 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
2bc00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2bc10 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
2bc20 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
2bc30 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
2bc40 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2bc50 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
2bc60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2bc70 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69  , seventh and ei
2bc80 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  ghth parameters,
2bc90 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
2bca0 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
2bcb0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
2bcc0 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
2bcd0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2bce0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2bcf0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2bd00 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
2bd10 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2bd20 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2bd30 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
2bd40 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
2bd50 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
2bd60 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  s must be passed
2bd70 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
2bd80 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
2bd90 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72  meters. ^An aggr
2bda0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2bdb0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2bdc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2bdd0 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
2bde0 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f  inal and NULL po
2bdf0 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61  inter must be pa
2be00 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
2be10 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
2be20 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
2be30 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2be40 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70  ate, pass NULL p
2be50 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20  ointers for all 
2be60 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
2be70 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
2be80 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
2be90 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2bea0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2beb0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
2bec0 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
2bed0 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
2bee0 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
2bef0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2bf00 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
2bf10 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
2bf20 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
2bf30 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
2bf40 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
2bf50 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
2bf60 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
2bf70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
2bf80 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
2bf90 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
2bfa0 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
2bfb0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
2bfc0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2bfd0 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
2bfe0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
2bff0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
2c000 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
2c010 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
2c020 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
2c030 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
2c040 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
2c050 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
2c060 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
2c070 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
2c080 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
2c090 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2c0a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2c0b0 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
2c0c0 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
2c0d0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
2c0e0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2c0f0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2c100 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
2c110 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
2c120 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
2c130 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
2c140 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
2c150 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
2c160 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2c170 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
2c180 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
2c190 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2c1a0 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
2c1b0 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
2c1c0 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
2c1d0 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
2c1e0 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
2c1f0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2c200 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
2c210 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
2c220 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
2c230 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
2c240 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
2c250 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2c260 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
2c270 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
2c280 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
2c290 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2c2a0 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
2c2b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2c2c0 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
2c2d0 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
2c2e0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
2c2f0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
2c300 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
2c310 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
2c320 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2c330 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
2c340 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
2c350 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
2c360 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
2c370 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
2c380 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2c390 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
2c3a0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
2c3b0 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
2c3c0 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
2c3d0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
2c3e0 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
2c3f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2c400 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
2c410 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
2c420 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2c430 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
2c440 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
2c450 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
2c460 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
2c470 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
2c480 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
2c490 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2c4a0 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
2c4b0 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
2c4c0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2c4d0 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
2c4e0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
2c4f0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
2c500 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2c510 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c520 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2c530 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2c540 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2c550 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2c560 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2c570 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2c580 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2c590 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2c5a0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2c5b0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2c5c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2c5d0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2c5e0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2c5f0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2c600 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49  ontext*).);.SQLI
2c610 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2c620 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c630 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
2c640 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
2c650 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
2c660 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2c670 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2c680 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2c690 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2c6a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2c6b0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2c6c0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2c6d0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2c6e0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2c6f0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2c700 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
2c710 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
2c720 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2c730 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2c740 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
2c750 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
2c760 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
2c770 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
2c780 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
2c790 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
2c7a0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
2c7b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2c7c0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2c7d0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2c7e0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
2c7f0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2c800 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2c810 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
2c820 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c830 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
2c840 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
2c850 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c860 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
2c870 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2c880 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
2c890 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
2c8a0 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
2c8b0 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
2c8c0 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
2c8d0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
2c8e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2c8f0 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64  8           1.#d
2c900 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2c910 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64  16LE        2.#d
2c920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2c930 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64  16BE        3.#d
2c940 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2c950 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
2c960 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
2c970 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
2c980 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
2c990 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
2c9a0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
2c9b0 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20  e_function only 
2c9c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2c9d0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
2c9e0 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
2c9f0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2ca00 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
2ca10 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
2ca20 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
2ca30 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
2ca40 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
2ca50 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
2ca60 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
2ca70 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
2ca80 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
2ca90 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
2caa0 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
2cab0 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
2cac0 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
2cad0 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
2cae0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
2caf0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
2cb00 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
2cb10 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
2cb20 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20   help encourage 
2cb30 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a  people to avoid.
2cb40 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66  ** using these f
2cb50 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65  unctions, we are
2cb60 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65   not going to te
2cb70 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79  ll you what they
2cb80 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
2cb90 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
2cba0 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50  ECATED.SQLITE_AP
2cbb0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
2cbc0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2cbd0 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
2cbe0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2cbf0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
2cc00 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2cc10 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
2cc20 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
2cc30 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
2cc40 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2cc50 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
2cc60 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
2cc70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
2cc80 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
2cc90 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
2cca0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2ccb0 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
2ccc0 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
2ccd0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
2cce0 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
2ccf0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
2cd00 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
2cd10 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
2cd20 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2cd30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
2cd40 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
2cd50 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
2cd60 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65  nt),void*,sqlite
2cd70 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
2cd80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2cd90 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
2cda0 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74  Function Paramet
2cdb0 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20  er Values.**.** 
2cdc0 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
2cdd0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2cde0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2cdf0 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
2ce00 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
2ce10 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
2ce20 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
2ce30 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
2ce40 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
2ce50 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2ce60 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ate..**.** The x
2ce70 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
2ce80 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
2ce90 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
2cea0 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
2ceb0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
2cec0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2ced0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2cee0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2cef0 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
2cf00 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
2cf10 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
2cf20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2cf30 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
2cf40 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
2cf50 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
2cf60 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
2cf70 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
2cf80 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2cf90 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2cfa0 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
2cfb0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2cfc0 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
2cfd0 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
2cfe0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2cff0 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
2d000 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
2d010 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
2d020 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
2d030 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2d040 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
2d050 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
2d060 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
2d070 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2d080 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
2d090 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
2d0a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
2d0b0 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
2d0c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2d0d0 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
2d0e0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
2d0f0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2d100 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2d110 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
2d120 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2d130 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
2d140 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
2d150 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
2d160 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
2d170 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
2d180 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d190 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
2d1a0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
2d1b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2d1c0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
2d1d0 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
2d1e0 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
2d1f0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2d200 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
2d210 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
2d220 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
2d230 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
2d240 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
2d250 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
2d260 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
2d270 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
2d280 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
2d290 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
2d2a0 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
2d2b0 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
2d2c0 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
2d2d0 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
2d2e0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
2d2f0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
2d300 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2d310 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
2d320 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
2d330 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
2d340 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
2d350 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
2d360 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
2d370 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
2d380 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2d390 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
2d3a0 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
2d3b0 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
2d3c0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2d3d0 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
2d3e0 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
2d3f0 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
2d400 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
2d410 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
2d420 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
2d430 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
2d440 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
2d450 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
2d460 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
2d470 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
2d480 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
2d490 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
2d4a0 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
2d4b0 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
2d4c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
2d4d0 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
2d4e0 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
2d4f0 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
2d500 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
2d510 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
2d520 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
2d530 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2d540 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
2d550 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d560 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
2d570 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
2d580 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
2d590 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
2d5a0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
2d5b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2d5c0 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
2d5d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2d5e0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2d5f0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
2d600 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2d610 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
2d620 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2d630 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
2d640 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2d650 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
2d660 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2d670 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
2d680 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2d690 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2d6a0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
2d6b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2d6c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2d6d0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2d6e0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2d6f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2d700 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
2d710 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
2d720 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2d730 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  PI double sqlite
2d740 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
2d750 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2d760 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2d770 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2d780 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2d790 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
2d7a0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2d7b0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
2d7c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2d7d0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2d7e0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2d7f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2d800 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
2d810 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
2d820 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d830 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2d840 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2d850 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2d860 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2d870 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
2d880 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2d890 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2d8a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2d8b0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
2d8c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
2d8d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2d8e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
2d8f0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2d900 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2d910 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
2d920 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
2d930 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
2d940 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2d950 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
2d960 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
2d970 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
2d980 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
2d990 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
2d9a0 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
2d9b0 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
2d9c0 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
2d9d0 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
2d9e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2d9f0 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
2da00 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2da10 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
2da20 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
2da30 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2da40 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2da50 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
2da60 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
2da70 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
2da80 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
2da90 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2daa0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
2dab0 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
2dac0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
2dad0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
2dae0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2daf0 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
2db00 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
2db10 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
2db20 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
2db30 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
2db40 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
2db50 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2db60 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
2db70 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
2db80 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
2db90 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
2dba0 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
2dbb0 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
2dbc0 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
2dbd0 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
2dbe0 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
2dbf0 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
2dc00 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
2dc10 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
2dc20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
2dc30 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2dc40 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
2dc50 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
2dc60 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
2dc70 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
2dc80 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
2dc90 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
2dca0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2dcb0 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
2dcc0 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
2dcd0 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
2dce0 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
2dcf0 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
2dd00 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
2dd10 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2dd20 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2dd30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2dd40 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20  if N is.** less 
2dd50 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
2dd60 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65   zero or if a me
2dd70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72  mory allocate er
2dd80 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
2dd90 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
2dda0 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
2ddb0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
2ddc0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2ddd0 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
2dde0 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
2ddf0 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
2de00 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
2de10 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
2de20 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
2de30 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2de40 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
2de50 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2de60 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
2de70 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
2de80 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
2de90 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
2dea0 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
2deb0 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  ocation.)^.**.**
2dec0 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74   ^SQLite automat
2ded0 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
2dee0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
2def0 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
2df00 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2df10 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67  xt() when the ag
2df20 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f  gregate query co
2df30 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
2df40 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2df50 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70  er must be a cop
2df60 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
2df70 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
2df80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
2df90 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
2dfa0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2dfb0 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70  .** to the xStep
2dfc0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
2dfd0 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
2dfe0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2dff0 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
2e000 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
2e010 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
2e020 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2e030 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2e040 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
2e050 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2e060 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2e070 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
2e080 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
2e090 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
2e0a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2e0b0 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
2e0c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
2e0d0 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
2e0e0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
2e0f0 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
2e100 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2e110 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2e120 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2e130 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
2e140 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
2e150 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
2e160 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2e170 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e180 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2e190 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2e1a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2e1b0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2e1c0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2e1d0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2e1e0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2e1f0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2e200 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
2e210 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2e220 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2e230 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2e240 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2e250 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
2e260 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
2e270 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
2e280 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2e290 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2e2a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e2b0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2e2c0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
2e2d0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
2e2e0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2e2f0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
2e300 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2e310 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2e320 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
2e330 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e340 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
2e350 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
2e360 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2e370 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
2e380 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2e390 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2e3a0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
2e3b0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
2e3c0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
2e3d0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2e3e0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
2e3f0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
2e400 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
2e410 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
2e420 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2e430 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e440 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
2e450 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
2e460 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
2e470 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
2e480 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
2e490 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
2e4a0 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
2e4b0 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
2e4c0 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
2e4d0 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
2e4e0 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
2e4f0 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
2e500 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2e510 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
2e520 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
2e530 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
2e540 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
2e550 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
2e560 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
2e570 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
2e580 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
2e590 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
2e5a0 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
2e5b0 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
2e5c0 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
2e5d0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
2e5e0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
2e5f0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
2e600 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
2e610 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
2e620 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2e630 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
2e640 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
2e650 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
2e660 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
2e670 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
2e680 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
2e690 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
2e6a0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
2e6b0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2e6c0 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
2e6d0 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
2e6e0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
2e6f0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2e700 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
2e710 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
2e720 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
2e730 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2e740 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2e750 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2e760 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
2e770 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
2e780 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
2e790 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
2e7a0 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
2e7b0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
2e7c0 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
2e7d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2e7e0 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20  unction. ^If no 
2e7f0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
2e800 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
2e810 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
2e820 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
2e830 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
2e840 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2e850 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
2e860 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
2e870 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
2e880 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
2e890 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
2e8a0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
2e8b0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
2e8c0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2e8d0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
2e8e0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
2e8f0 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
2e900 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
2e910 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
2e920 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
2e930 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
2e940 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
2e950 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2e960 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2e970 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
2e980 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2e990 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2e9a0 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
2e9b0 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
2e9c0 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
2e9d0 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e   destroyed..** ^
2e9e0 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
2e9f0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
2ea00 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2ea10 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ctor.** function
2ea20 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
2ea30 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2ea40 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2ea50 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
2ea60 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65  etadata when the
2ea70 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
2ea80 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
2ea90 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20  r changes.** or 
2eaa0 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  when the SQL sta
2eab0 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73  tement completes
2eac0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
2ead0 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  s first..**.** S
2eae0 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
2eaf0 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75   call the destru
2eb00 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65  ctor and drop me
2eb10 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a  tadata on any.**
2eb20 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
2eb30 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
2eb40 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e  y time.  ^The on
2eb50 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
2eb60 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
2eb70 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
2eb80 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
2eb90 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
2eba0 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  pped..**.** ^(In
2ebb0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
2ebc0 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
2ebd0 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
2ebe0 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
2ebf0 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
2ec00 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
2ec10 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
2ec20 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
2ec30 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
2ec40 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29  d [parameters].)
2ec50 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ^.**.** These ro
2ec60 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
2ec70 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2ec80 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2ec90 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
2eca0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2ecb0 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
2ecc0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
2ecd0 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
2ece0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2ecf0 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t N);.SQLITE_API
2ed00 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65   void sqlite3_se
2ed10 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
2ed20 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2ed30 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
2ed40 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
2ed50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2ed60 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
2ed70 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
2ed80 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
2ed90 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
2eda0 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
2edb0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
2edc0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
2edd0 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
2ede0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
2edf0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2ee00 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2ee10 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
2ee20 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
2ee30 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
2ee40 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
2ee50 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
2ee60 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
2ee70 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
2ee80 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
2ee90 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
2eea0 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
2eeb0 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
2eec0 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
2eed0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2eee0 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
2eef0 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
2ef00 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
2ef10 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
2ef20 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
2ef30 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
2ef40 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
2ef50 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
2ef60 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2ef70 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
2ef80 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
2ef90 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
2efa0 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
2efb0 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
2efc0 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
2efd0 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
2efe0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2eff0 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
2f000 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
2f010 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
2f020 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2f030 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
2f040 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2f050 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
2f060 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
2f070 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f080 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
2f090 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
2f0a0 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
2f0b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2f0c0 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
2f0d0 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
2f0e0 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
2f0f0 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
2f100 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2f110 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
2f120 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f130 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
2f140 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f150 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
2f160 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2f170 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
2f180 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2f190 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
2f1a0 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
2f1b0 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
2f1c0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
2f1d0 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
2f1e0 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
2f1f0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
2f200 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f210 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
2f220 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
2f230 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
2f240 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
2f250 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
2f260 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f270 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
2f280 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2f290 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
2f2a0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
2f2b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2f2c0 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
2f2d0 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
2f2e0 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
2f2f0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
2f300 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
2f310 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
2f320 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
2f330 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
2f340 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
2f350 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
2f360 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
2f370 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
2f380 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
2f390 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f3a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2f3b0 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
2f3c0 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
2f3d0 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
2f3e0 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
2f3f0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2f400 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2f410 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
2f420 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
2f430 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
2f440 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
2f450 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
2f460 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f470 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
2f480 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2f490 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
2f4a0 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
2f4b0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2f4c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2f4d0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
2f4e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f4f0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
2f500 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
2f510 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
2f520 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
2f530 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
2f540 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
2f550 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
2f560 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
2f570 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
2f580 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f590 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
2f5a0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2f5b0 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
2f5c0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
2f5d0 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
2f5e0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
2f5f0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
2f600 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
2f610 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2f620 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
2f630 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
2f640 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
2f650 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
2f660 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
2f670 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
2f680 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
2f690 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2f6a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2f6b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2f6c0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
2f6d0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2f6e0 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
2f6f0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
2f700 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
2f710 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
2f720 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
2f730 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
2f740 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
2f750 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
2f760 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
2f770 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
2f780 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f790 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
2f7a0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
2f7b0 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
2f7c0 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
2f7d0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
2f7e0 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
2f7f0 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
2f800 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
2f810 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2f820 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
2f830 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f840 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
2f850 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
2f860 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
2f870 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
2f880 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
2f890 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
2f8a0 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
2f8b0 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
2f8c0 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
2f8d0 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
2f8e0 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
2f8f0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
2f900 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f910 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
2f920 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
2f930 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
2f940 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
2f950 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
2f960 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
2f970 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
2f980 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
2f990 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
2f9a0 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
2f9b0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
2f9c0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
2f9d0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
2f9e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f9f0 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
2fa00 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
2fa10 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
2fa20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2fa30 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
2fa40 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
2fa50 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
2fa60 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
2fa70 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
2fa80 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
2fa90 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
2faa0 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
2fab0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2fac0 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
2fad0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
2fae0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
2faf0 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
2fb00 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
2fb10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
2fb20 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
2fb30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fb40 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
2fb50 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2fb60 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2fb70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2fb80 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2fb90 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
2fba0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2fbb0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
2fbc0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
2fbd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fbe0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
2fbf0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2fc00 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2fc10 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
2fc20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2fc30 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
2fc40 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2fc50 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
2fc60 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
2fc70 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2fc80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2fc90 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
2fca0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2fcb0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
2fcc0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2fcd0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2fce0 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
2fcf0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2fd00 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
2fd10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fd20 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
2fd30 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2fd40 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
2fd50 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2fd60 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
2fd70 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
2fd80 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
2fd90 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2fda0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2fdb0 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
2fdc0 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
2fdd0 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
2fde0 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
2fdf0 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
2fe00 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
2fe10 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
2fe20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
2fe30 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51  ectively..** ^SQ
2fe40 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
2fe50 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
2fe60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2fe70 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
2fe80 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2fe90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fea0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2feb0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
2fec0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2fed0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2fee0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2fef0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
2ff00 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
2ff10 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
2ff20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
2ff30 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
2ff40 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
2ff50 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
2ff60 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
2ff70 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2ff80 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2ff90 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2ffa0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
2ffb0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
2ffc0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
2ffd0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
2ffe0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
2fff0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
30000 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
30010 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
30020 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
30030 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  ion result..** ^
30040 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
30050 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
30060 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
30070 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
30080 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
30090 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
300a0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
300b0 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
300c0 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
300d0 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
300e0 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
300f0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
30100 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
30110 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
30120 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
30130 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
30140 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
30150 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
30160 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a  erfaces or to.**
30170 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30180 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
30190 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
301a0 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
301b0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
301c0 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
301d0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
301e0 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
301f0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
30200 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f  t.** copy the co
30210 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72  ntent of the par
30220 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20  ameter nor call 
30230 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  a destructor on 
30240 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77  the content.** w
30250 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
30260 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
30270 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
30280 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
30290 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
302a0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
302b0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
302c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
302d0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
302e0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
302f0 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
30300 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
30310 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
30320 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
30330 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
30340 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
30350 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
30360 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
30370 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
30380 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
30390 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
303a0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
303b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
303c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
303d0 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
303e0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
303f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30400 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
30410 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
30420 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
30430 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
30440 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
30450 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
30460 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30470 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
30480 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
30490 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
304a0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
304b0 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
304c0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
304d0 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
304e0 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
304f0 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
30500 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
30510 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
30520 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
30530 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
30540 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
30550 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30560 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
30570 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
30580 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
30590 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
305a0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
305b0 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
305c0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
305d0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
305e0 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
305f0 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
30600 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
30610 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
30620 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
30630 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
30640 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
30650 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
30660 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
30670 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
30680 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
30690 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
306a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
306b0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
306c0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
306d0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
306e0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
306f0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
30700 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
30710 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30720 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54  , double);.SQLIT
30730 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
30740 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
30750 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30760 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
30770 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
30780 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
30790 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
307a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
307b0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
307c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
307d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
307e0 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
307f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
30800 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
30810 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30820 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
30830 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
30840 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
30850 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30860 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
30870 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
30880 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
30890 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
308a0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
308b0 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  xt*, int);.SQLIT
308c0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
308d0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
308e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
308f0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
30900 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
30910 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30920 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
30930 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
30940 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
30950 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
30960 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
30970 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
30980 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
30990 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
309a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
309b0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
309c0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
309d0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
309e0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
309f0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
30a00 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30a10 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
30a20 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
30a30 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
30a40 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
30a50 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
30a60 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
30a70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30a80 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
30a90 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
30aa0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
30ab0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
30ac0 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ult_value(sqlite
30ad0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
30ae0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
30af0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
30b00 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
30b10 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
30b20 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
30b30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30b40 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
30b50 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
30b60 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
30b70 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76  tions add, remov
30b80 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b  e, or modify a [
30b90 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63  collation] assoc
30ba0 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
30bb0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
30bc0 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
30bd0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
30be0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
30bf0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
30c00 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55  collation is a U
30c10 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66  TF-8 string.** f
30c20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
30c30 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e  e_collation() an
30c40 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  d sqlite3_create
30c50 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a  _collation_v2().
30c60 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  ** and a UTF-16 
30c70 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
30c80 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20   byte order for 
30c90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
30ca0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
30cb0 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65   ^Collation name
30cc0 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65  s that compare e
30cd0 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74  qual according t
30ce0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69  o [sqlite3_strni
30cf0 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f  cmp()] are.** co
30d00 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74  nsidered to be t
30d10 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
30d20 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20  .** ^(The third 
30d30 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52  argument (eTextR
30d40 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  ep) must be one 
30d50 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
30d60 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  :.** <ul>.** <li
30d70 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  > [SQLITE_UTF8],
30d80 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
30d90 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16LE],.** <l
30da0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
30db0 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BE],.** <li> [SQ
30dc0 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a  LITE_UTF16], or.
30dd0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
30de0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a  UTF16_ALIGNED]..
30df0 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54  ** </ul>)^.** ^T
30e00 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
30e10 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20  ment determines 
30e20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
30e30 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a  strings passed.*
30e40 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  * to the collati
30e50 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
30e60 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e  back, xCallback.
30e70 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
30e80 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c  _UTF16] and [SQL
30e90 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
30ea0 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54  D] values for eT
30eb0 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20  extRep.** force 
30ec0 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54  strings to be UT
30ed0 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20  F16 with native 
30ee0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
30ef0 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
30f00 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
30f10 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f   for eTextRep fo
30f20 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20  rces strings to 
30f30 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65  begin.** on an e
30f40 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73  ven byte address
30f50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
30f60 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41  rth argument, pA
30f70 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63  rg, is an applic
30f80 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
30f90 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  er that is passe
30fa0 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20  d.** through as 
30fb0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
30fc0 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  nt to the collat
30fd0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
30fe0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
30ff0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
31000 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20  , xCallback, is 
31010 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
31020 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
31030 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c  ion..** ^Multipl
31040 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
31050 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67  tions can be reg
31060 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
31070 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a  e same name but.
31080 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ** with differen
31090 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d  t eTextRep param
310a0 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65  eters and SQLite
310b0 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65   will use whiche
310c0 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ver.** function 
310d0 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61  requires the lea
310e0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
310f0 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e  a transformation
31100 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61  ..** ^If the xCa
31110 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
31120 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
31130 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
31140 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65  ion is.** delete
31150 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f  d.  ^When all co
31160 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
31170 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d  s having the sam
31180 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74  e name are delet
31190 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c  ed,.** that coll
311a0 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ation is no long
311b0 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  er usable..**.**
311c0 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20   ^The collating 
311d0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
311e0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
311f0 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  h a copy of the 
31200 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61  pArg .** applica
31210 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
31220 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73  r and with two s
31230 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e  trings in the en
31240 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
31250 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74  .** by the eText
31260 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Rep argument.  T
31270 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
31280 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72  ction must retur
31290 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  n an.** integer 
312a0 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65  that is negative
312b0 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74  , zero, or posit
312c0 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69  ive.** if the fi
312d0 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
312e0 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74  ss than, equal t
312f0 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  o, or greater th
31300 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a  an the second,.*
31310 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
31320 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
31330 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79  ction must alway
31340 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
31350 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65  e answer.** give
31360 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  n the same input
31370 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  s.  If two or mo
31380 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  re collating fun
31390 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73  ctions are regis
313a0 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  tered.** to the 
313b0 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e  same collation n
313c0 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65  ame (using diffe
313d0 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61  rent eTextRep va
313e0 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a  lues) then all.*
313f0 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65  * must give an e
31400 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72  quivalent answer
31410 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69   when invoked wi
31420 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74  th equivalent st
31430 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f  rings..** The co
31440 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
31450 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66   must obey the f
31460 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74  ollowing propert
31470 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73  ies for all.** s
31480 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64  trings A, B, and
31490 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a   C:.**.** <ol>.*
314a0 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74  * <li> If A==B t
314b0 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69  hen B==A..** <li
314c0 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d  > If A==B and B=
314d0 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a  =C then A==C..**
314e0 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
314f0 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20  THEN B&gt;A..** 
31500 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61  <li> If A&lt;B a
31510 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41  nd B&lt;C then A
31520 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  &lt;C..** </ol>.
31530 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61  **.** If a colla
31540 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61  ting function fa
31550 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61  ils any of the a
31560 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  bove constraints
31570 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c   and that.** col
31580 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
31590 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61  is  registered a
315a0 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  nd used, then th
315b0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  e behavior of SQ
315c0 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  Lite.** is undef
315d0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
315e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
315f0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
31600 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
31610 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
31620 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65  on().** with the
31630 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74   addition that t
31640 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
31650 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
31660 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20  on pArg when.** 
31670 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
31680 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
31690 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67  d..** ^Collating
316a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64   functions are d
316b0 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79  eleted when they
316c0 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
316d0 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c  by later.** call
316e0 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  s to the collati
316f0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
31700 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
31710 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
31720 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c  onnection] is cl
31730 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  osed using [sqli
31740 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
31750 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f  .** ^The xDestro
31760 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75  y callback is <u
31770 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20  >not</u> called 
31780 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74  if the .** sqlit
31790 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
317a0 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f  ion_v2() functio
317b0 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63  n fails.  Applic
317c0 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f  ations that invo
317d0 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  ke.** sqlite3_cr
317e0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
317f0 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  2() with a non-N
31800 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67  ULL xDestroy arg
31810 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a  ument should .**
31820 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
31830 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f  n code and dispo
31840 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  se of the applic
31850 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
31860 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73  er.** themselves
31870 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70   rather than exp
31880 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f  ecting SQLite to
31890 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f   deal with it fo
318a0 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20  r them..** This 
318b0 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  is different fro
318c0 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51  m every other SQ
318d0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
318e0 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e   The inconsisten
318f0 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74  cy .** is unfort
31900 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74  unate but cannot
31910 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68   be changed with
31920 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63  out breaking bac
31930 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61  kwards .** compa
31940 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
31950 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69  See also:  [sqli
31960 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
31970 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  eded()] and [sql
31980 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
31990 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 53  eeded16()]..*/.S
319a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
319b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
319c0 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
319d0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
319e0 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
319f0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
31a00 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
31a10 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
31a20 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
31a30 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
31a40 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
31a50 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
31a60 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
31a70 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
31a80 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
31a90 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
31aa0 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
31ab0 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
31ac0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
31ad0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
31ae0 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
31af0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
31b00 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  id*).);.SQLITE_A
31b10 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
31b20 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
31b30 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
31b40 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
31b50 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
31b60 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
31b70 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
31b80 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
31b90 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
31ba0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
31bb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31bc0 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
31bd0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
31be0 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e   ^To avoid havin
31bf0 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
31c00 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
31c10 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
31c20 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
31c30 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
31c40 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
31c50 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
31c60 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
31c70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
31c80 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76  ction] to be inv
31c90 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
31ca0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
31cb0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
31cc0 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
31cd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63  .** ^If the func
31ce0 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
31cf0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
31d00 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
31d10 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
31d20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
31d30 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
31d40 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
31d50 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
31d60 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
31d70 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66  ed in UTF-8. ^If
31d80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
31d90 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
31da0 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
31db0 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
31dc0 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
31dd0 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
31de0 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c  order..** ^A cal
31df0 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
31e00 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
31e10 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61  e existing colla
31e20 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c  tion-needed call
31e30 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68  back..**.** ^(Wh
31e40 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
31e50 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
31e60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
31e70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
31e80 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
31e90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
31ea0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
31eb0 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
31ec0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
31ed0 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
31ee0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
31ef0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
31f00 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
31f10 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
31f20 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
31f30 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
31f40 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
31f50 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
31f60 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
31f70 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
31f80 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
31f90 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
31fa0 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
31fb0 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
31fc0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
31fd0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
31fe0 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
31ff0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
32000 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  e.)^.**.** The c
32010 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
32020 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
32030 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
32040 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
32050 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32060 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
32070 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32080 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
32090 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
320a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
320b0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
320c0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
320d0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
320e0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
320f0 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  void*, .  void(*
32100 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
32110 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
32120 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 53 51  nst char*).);.SQ
32130 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
32140 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
32150 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
32160 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
32170 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
32180 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
32190 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
321a0 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c  ).);..#ifdef SQL
321b0 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a  ITE_HAS_CODEC./*
321c0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
321d0 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
321e0 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
321f0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
32200 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
32210 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
32220 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
32230 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
32240 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
32250 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
32260 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
32270 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
32280 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  QLite..*/.SQLITE
32290 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
322a0 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  _key(.  sqlite3 
322b0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
322c0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
322d0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
322e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
322f0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
32300 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20       /* The key 
32310 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61  */.);../*.** Cha
32320 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61  nge the key on a
32330 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e  n open database.
32340 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74    If the current
32350 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
32360 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74  .** encrypted, t
32370 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
32380 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66   encrypt it.  If
32390 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77   pNew==0 or nNew
323a0 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61  ==0, the.** data
323b0 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65  base is decrypte
323c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  d..**.** The cod
323d0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
323e0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
323f0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
32400 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
32410 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
32420 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
32430 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
32440 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
32450 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
32460 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
32470 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
32480 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
32490 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
324a0 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
324b0 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
324c0 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
324d0 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61  key for a SEE da
324e0 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
324f0 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
32500 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72  one of the SEE r
32510 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
32520 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  k..*/.SQLITE_API
32530 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63   void sqlite3_ac
32540 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f  tivate_see(.  co
32550 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
32560 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
32570 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
32580 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
32590 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e  #ifdef SQLITE_EN
325a0 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a  ABLE_CEROD./*.**
325b0 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
325c0 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
325d0 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65  a CEROD database
325e0 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
325f0 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
32600 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69   the CEROD routi
32610 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
32620 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
32630 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
32640 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73  te_cerod(.  cons
32650 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
32660 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
32670 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
32680 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  */.);.#endif../*
32690 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
326a0 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
326b0 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
326c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
326d0 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
326e0 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
326f0 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
32700 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
32710 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
32720 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
32730 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
32740 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
32750 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
32760 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
32770 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
32780 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
32790 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
327a0 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
327b0 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
327c0 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
327d0 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
327e0 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
327f0 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  cond. The number
32800 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
32810 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
32820 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
32830 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
32840 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
32850 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  urned..**.** ^SQ
32860 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
32870 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
32880 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
32890 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
328a0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
328b0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
328c0 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53  ject.  If the xS
328d0 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a  leep() method.**
328e0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
328f0 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  VFS is not imple
32900 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79  mented correctly
32910 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  , or not impleme
32920 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20  nted at.** all, 
32930 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
32940 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65  r of sqlite3_sle
32950 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65  ep() may deviate
32960 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69   from the descri
32970 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  ption.** in the 
32980 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
32990 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  phs..*/.SQLITE_A
329a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
329b0 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  leep(int);../*.*
329c0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
329d0 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
329e0 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
329f0 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49   Files.**.** ^(I
32a00 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
32a10 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
32a20 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
32a30 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
32a40 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
32a50 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
32a60 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
32a70 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
32a80 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
32a90 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e  SQLite when usin
32aa0 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71  g a built-in [sq
32ab0 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d  lite3_vfs | VFS]
32ac0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  .** will be plac
32ad0 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
32ae0 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69  tory.)^  ^If thi
32af0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
32b00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
32b10 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72   then SQLite per
32b20 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66  forms a search f
32b30 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
32b40 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
32b50 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
32b60 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
32b70 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
32b80 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
32b90 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
32ba0 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
32bb0 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
32bc0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
32bd0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
32be0 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
32bf0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
32c00 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
32c10 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
32c20 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
32c30 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
32c40 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
32c50 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
32c60 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
32c70 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
32c80 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
32c90 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
32ca0 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
32cb0 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
32cc0 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
32cd0 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
32ce0 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
32cf0 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
32d00 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
32d10 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65  ^The [temp_store
32d20 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
32d30 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
32d40 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
32d50 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
32d60 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
32d70 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
32d80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
32d90 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
32da0 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
32db0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
32dc0 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
32dd0 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
32de0 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
32df0 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
32e00 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
32e10 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
32e20 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
32e30 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
32e40 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
32e50 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
32e60 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
32e70 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
32e80 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
32e90 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
32ea0 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
32eb0 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
32ec0 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
32ed0 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
32ee0 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
32ef0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
32f00 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
32f10 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
32f20 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
32f30 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
32f40 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
32f50 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ided..*/.SQLITE_
32f60 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52  API SQLITE_EXTER
32f70 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
32f80 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
32f90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32fa0 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43   Test For Auto-C
32fb0 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45  ommit Mode.** KE
32fc0 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d  YWORDS: {autocom
32fd0 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  mit mode}.**.** 
32fe0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
32ff0 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
33000 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
33010 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
33020 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
33030 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
33040 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
33050 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
33060 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
33070 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d  ively.  ^Autocom
33080 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
33090 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41  y default..** ^A
330a0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
330b0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
330c0 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
330d0 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
330e0 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61  t mode is re-ena
330f0 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49  bled by a [COMMI
33100 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
33110 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61  ..**.** If certa
33120 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
33130 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74  rs occur on a st
33140 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
33150 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74   multi-statement
33160 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
33170 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e  (errors includin
33180 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c  g [SQLITE_FULL],
33190 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c   [SQLITE_IOERR],
331a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
331b0 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  M], [SQLITE_BUSY
331c0 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ], and [SQLITE_I
331d0 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20  NTERRUPT]) then 
331e0 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  the.** transacti
331f0 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c  on might be roll
33200 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
33210 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79  cally.  The only
33220 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20   way to.** find 
33230 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69  out whether SQLi
33240 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
33250 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
33260 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
33270 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
33280 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
33290 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
332a0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
332b0 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
332c0 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
332d0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
332e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
332f0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
33300 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20  s running, then 
33310 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
33320 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
33330 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
33340 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
33350 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
33360 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
33370 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
33380 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
33390 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
333a0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
333b0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
333c0 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
333d0 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
333e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
333f0 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
33400 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
33410 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
33420 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62  gs.  ^The [datab
33430 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
33440 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
33450 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
33460 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
33470 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33480 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74  n].** that was t
33490 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
334a0 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
334b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
334c0 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
334d0 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
334e0 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
334f0 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
33500 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
33510 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  place..*/.SQLITE
33520 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71  _API sqlite3 *sq
33530 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
33540 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
33550 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33560 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
33570 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33580 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
33590 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
335a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
335b0 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
335c0 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
335d0 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
335e0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
335f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33600 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53  on] pDb.  ^If pS
33610 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
33620 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
33630 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
33640 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
33650 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
33660 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
33670 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
33680 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
33690 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65  pDb.  ^If no pre
336a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
336b0 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
336c0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
336d0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
336e0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
336f0 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
33700 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
33710 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
33720 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
33730 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
33740 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
33750 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
33760 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
33770 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
33780 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
33790 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 53  LL pointer..*/.S
337a0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
337b0 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f  3_stmt *sqlite3_
337c0 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65  next_stmt(sqlite
337d0 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f  3 *pDb, sqlite3_
337e0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
337f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
33800 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61  ommit And Rollba
33810 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ck Notification 
33820 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
33830 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
33840 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  mit_hook() inter
33850 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
33860 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
33870 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
33880 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
33890 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43  ransaction is [C
338a0 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65  OMMIT | committe
338b0 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  d]..** ^Any call
338c0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
338d0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
338e0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
338f0 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
33900 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
33910 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
33920 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20  ridden..** ^The 
33930 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
33940 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
33950 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
33960 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
33970 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
33980 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
33990 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c  saction is [ROLL
339a0 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61  BACK | rolled ba
339b0 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ck]..** ^Any cal
339c0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
339d0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
339e0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
339f0 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
33a00 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
33a10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
33a20 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
33a30 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
33a40 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
33a50 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  gh to the callba
33a60 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ck..** ^If the c
33a70 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d  allback on a com
33a80 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f  mit hook functio
33a90 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  n returns non-ze
33aa0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ro,.** then the 
33ab0 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72  commit is conver
33ac0 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
33ad0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
33ae0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
33af0 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73  ook(D,C,P) and s
33b00 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
33b10 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63  hook(D,C,P) func
33b20 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20  tions.** return 
33b30 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66  the P argument f
33b40 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
33b50 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d   call of the sam
33b60 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e  e function.** on
33b70 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
33b80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
33b90 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a  D, or NULL for.*
33ba0 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  * the first call
33bb0 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69   for each functi
33bc0 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54  on on D..**.** T
33bd0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c  he callback impl
33be0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
33bf0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
33c00 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
33c10 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
33c20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
33c30 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c   invoked the cal
33c40 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69  lback.  Any acti
33c50 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
33c60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
33c70 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
33c80 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
33c90 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
33ca0 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
33cb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
33cc0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
33cd0 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a  red the commit.*
33ce0 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  * or rollback ho
33cf0 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ok in the first 
33d00 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  place..** Note t
33d10 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
33d20 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
33d30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
33d40 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
33d50 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
33d60 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
33d70 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
33d80 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
33d90 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
33da0 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55  Registering a NU
33db0 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  LL function disa
33dc0 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  bles the callbac
33dd0 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74  k..**.** ^When t
33de0 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63  he commit hook c
33df0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
33e00 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
33e10 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70  e [COMMIT].** op
33e20 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77  eration is allow
33e30 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e  ed to continue n
33e40 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68  ormally.  ^If th
33e50 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a  e commit hook.**
33e60 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
33e70 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d  o, then the [COM
33e80 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65  MIT] is converte
33e90 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41  d into a [ROLLBA
33ea0 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c  CK]..** ^The rol
33eb0 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e  lback hook is in
33ec0 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62  voked on a rollb
33ed0 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73  ack that results
33ee0 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a   from a commit.*
33ef0 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67  * hook returning
33f00 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20   non-zero, just 
33f10 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77  as it would be w
33f20 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f  ith any other ro
33f30 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46  llback..**.** ^F
33f40 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
33f50 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74  of this API, a t
33f60 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61  ransaction is sa
33f70 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a  id to have been.
33f80 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69  ** rolled back i
33f90 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52  f an explicit "R
33fa0 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65  OLLBACK" stateme
33fb0 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20  nt is executed, 
33fc0 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f  or.** an error o
33fd0 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75  r constraint cau
33fe0 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20  ses an implicit 
33ff0 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75  rollback to occu
34000 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62  r..** ^The rollb
34010 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
34020 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
34030 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
34040 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
34050 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
34060 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73  ause the databas
34070 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
34080 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  closed..**.** Se
34090 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
340a0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
340b0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
340c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
340d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   *sqlite3_commit
340e0 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
340f0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
34100 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  oid*);.SQLITE_AP
34110 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
34120 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71  rollback_hook(sq
34130 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28  lite3*, void(*)(
34140 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b  void *), void*);
34150 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34160 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f  : Data Change No
34170 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
34180 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
34190 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
341a0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
341b0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
341c0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
341d0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
341e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
341f0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
34200 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
34210 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
34220 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77  d whenever a row
34230 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
34240 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
34250 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
34260 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
34270 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
34280 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f  s function.** fo
34290 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
342a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
342b0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
342c0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
342d0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
342e0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e  inter to the fun
342f0 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20  ction to invoke 
34300 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73  when a.** row is
34310 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
34320 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
34330 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
34340 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c  ument to the cal
34350 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
34360 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67  of the third arg
34370 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
34380 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
34390 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  )..** ^The secon
343a0 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d  d callback argum
343b0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
343c0 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
343d0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a  SQLITE_DELETE],.
343e0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  ** or [SQLITE_UP
343f0 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67  DATE], depending
34400 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f   on the operatio
34410 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  n that caused th
34420 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f  e callback.** to
34430 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20   be invoked..** 
34440 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66  ^The third and f
34450 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
34460 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
34470 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
34480 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
34490 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61  ase and table na
344a0 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  me containing th
344b0 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a  e affected row..
344c0 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61  ** ^The final ca
344d0 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72  llback parameter
344e0 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
344f0 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e  of the row..** ^
34500 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61  In the case of a
34510 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69  n update, this i
34520 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66  s the [rowid] af
34530 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74  ter the update t
34540 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a  akes place..**.*
34550 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68  * ^(The update h
34560 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ook is not invok
34570 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c  ed when internal
34580 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61   system tables a
34590 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28  re.** modified (
345a0 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74  i.e. sqlite_mast
345b0 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65  er and sqlite_se
345c0 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a  quence).)^.**.**
345d0 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74   ^In the current
345e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c   implementation,
345f0 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
34600 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  .** is not invok
34610 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74  ed when duplicat
34620 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c  ion rows are del
34630 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20  eted because of 
34640 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49  an.** [ON CONFLI
34650 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54  CT | ON CONFLICT
34660 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65   REPLACE] clause
34670 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75  .  ^Nor is the u
34680 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e  pdate hook.** in
34690 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20  voked when rows 
346a0 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e  are deleted usin
346b0 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20  g the [truncate 
346c0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a  optimization]..*
346d0 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73  * The exceptions
346e0 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73   defined in this
346f0 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74   paragraph might
34700 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
34710 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
34720 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
34730 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
34740 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
34750 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
34760 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
34770 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
34780 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34790 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
347a0 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41   update hook.  A
347b0 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
347c0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
347d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
347e0 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
347f0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
34800 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
34810 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
34820 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
34830 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75   triggered the u
34840 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e  pdate hook..** N
34850 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
34860 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
34870 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
34880 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
34890 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
348a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
348b0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
348c0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
348d0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
348e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
348f0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43  _update_hook(D,C
34900 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ,P) function.** 
34910 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72  returns the P ar
34920 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
34930 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a  previous call.**
34940 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
34950 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34960 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f  n] D, or NULL fo
34970 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63  r.** the first c
34980 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  all on D..**.** 
34990 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
349a0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
349b0 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  k()] and [sqlite
349c0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
349d0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  )].** interfaces
349e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
349f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70  void *sqlite3_up
34a00 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c  date_hook(.  sql
34a10 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  ite3*, .  void(*
34a20 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68  )(void *,int ,ch
34a30 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20  ar const *,char 
34a40 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f  const *,sqlite3_
34a50 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a  int64),.  void*.
34a60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34a70 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
34a80 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67  sable Shared Pag
34a90 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59 57  er Cache.** KEYW
34aa0 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61  ORDS: {shared ca
34ab0 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  che}.**.** ^(Thi
34ac0 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  s routine enable
34ad0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
34ae0 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65  e sharing of the
34af0 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a   database cache.
34b00 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61  ** and schema da
34b10 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65  ta structures be
34b20 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20  tween [database 
34b30 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e  connection | con
34b40 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20  nections].** to 
34b50 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
34b60 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e  e. Sharing is en
34b70 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67  abled if the arg
34b80 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a  ument is true.**
34b90 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66   and disabled if
34ba0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   the argument is
34bb0 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20   false.)^.**.** 
34bc0 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69  ^Cache sharing i
34bd0 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69  s enabled and di
34be0 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e  sabled for an en
34bf0 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a  tire process..**
34c00 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67   This is a chang
34c10 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76  e as of SQLite v
34c20 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e  ersion 3.5.0. In
34c30 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20   prior versions 
34c40 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68  of SQLite,.** sh
34c50 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65  aring was enable
34c60 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f  d or disabled fo
34c70 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65  r each thread se
34c80 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
34c90 5e 28 54 68 65 20 63 61 63 68 65 20 73 68 61 72  ^(The cache shar
34ca0 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20  ing mode set by 
34cb0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65  this interface e
34cc0 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65  ffects all subse
34cd0 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
34ce0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
34cf0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
34d00 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71  n_v2()], and [sq
34d10 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
34d20 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74  .** Existing dat
34d30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34d40 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74  s continue use t
34d50 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a  he sharing mode.
34d60 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65  ** that was in e
34d70 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d  ffect at the tim
34d80 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e  e they were open
34d90 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ed.)^.**.** ^(Th
34da0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
34db0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ns [SQLITE_OK] i
34dc0 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77  f shared cache w
34dd0 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  as enabled or di
34de0 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73  sabled.** succes
34df0 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72  sfully.  An [err
34e00 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
34e10 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 29  rned otherwise.)
34e20 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20  ^.**.** ^Shared 
34e30 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65  cache is disable
34e40 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75  d by default. Bu
34e50 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61  t this might cha
34e60 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  nge in.** future
34e70 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
34e80 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ite.  Applicatio
34e90 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f  ns that care abo
34ea0 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ut shared.** cac
34eb0 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c  he setting shoul
34ec0 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69  d set it explici
34ed0 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41  tly..**.** See A
34ee0 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68  lso:  [SQLite Sh
34ef0 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d  ared-Cache Mode]
34f00 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
34f10 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
34f20 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69  e_shared_cache(i
34f30 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
34f40 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f  3REF: Attempt To
34f50 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72   Free Heap Memor
34f60 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
34f70 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
34f80 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  ory() interface 
34f90 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65  attempts to free
34fa0 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68   N bytes.** of h
34fb0 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65  eap memory by de
34fc0 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65  allocating non-e
34fd0 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20  ssential memory 
34fe0 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68  allocations.** h
34ff0 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62  eld by the datab
35000 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20 20 4d  ase library.   M
35010 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61  emory used to ca
35020 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  che database.** 
35030 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65  pages to improve
35040 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20   performance is 
35050 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f  an example of no
35060 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
35070 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  ry..** ^sqlite3_
35080 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
35090 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
350a0 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74  ber of bytes act
350b0 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20  ually freed,.** 
350c0 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d  which might be m
350d0 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e  ore or less than
350e0 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75   the amount requ
350f0 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ested..** ^The s
35100 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
35110 65 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e 65 20  emory() routine 
35120 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75 72  is a no-op retur
35130 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66 20  ning zero.** if 
35140 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20 63 6f  SQLite is not co
35150 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
35160 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
35170 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a  Y_MANAGEMENT]..*
35180 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
35190 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
351a0 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
351b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
351c0 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e  mpose A Limit On
351d0 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a   Heap Size.**.**
351e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f   ^The sqlite3_so
351f0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
35200 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
35210 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20   and/or queries 
35220 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69  the.** soft limi
35230 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  t on the amount 
35240 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
35250 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
35260 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  ated by SQLite..
35270 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76  ** ^SQLite striv
35280 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20  es to keep heap 
35290 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69  memory utilizati
352a0 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66  on below the sof
352b0 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20  t heap.** limit 
352c0 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20  by reducing the 
352d0 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
352e0 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65  held in the page
352f0 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61   cache.** as hea
35300 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20  p memory usages 
35310 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c  approaches the l
35320 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f  imit..** ^The so
35330 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
35340 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20   "soft" because 
35350 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69  even though SQLi
35360 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74  te strives to st
35370 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20  ay.** below the 
35380 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65  limit, it will e
35390 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20  xceed the limit 
353a0 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65  rather than gene
353b0 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49  rate.** an [SQLI
353c0 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e  TE_NOMEM] error.
353d0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
353e0 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
353f0 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76  limit .** is adv
35400 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  isory only..**.*
35410 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61  * ^The return va
35420 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
35430 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
35440 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65  64() is the size
35450 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20   of.** the soft 
35460 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72  heap limit prior
35470 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e   to the call.  ^
35480 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
35490 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
354a0 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20   then no change 
354b0 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73  is made to the s
354c0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20  oft heap limit. 
354d0 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72   Hence, the curr
354e0 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74  ent.** size of t
354f0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
35500 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  it can be determ
35510 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67  ined by invoking
35520 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  .** sqlite3_soft
35530 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
35540 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 20  with a negative 
35550 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
35560 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
35570 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20   N is zero then 
35580 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
35590 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e  mit is disabled.
355a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66  .**.** ^(The sof
355b0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
355c0 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20  not enforced in 
355d0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
355e0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66  ementation.** if
355f0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
35600 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74  following condit
35610 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a  ions are true:.*
35620 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
35630 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20  > The soft heap 
35640 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20  limit is set to 
35650 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65  zero..** <li> Me
35660 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20  mory accounting 
35670 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  is disabled usin
35680 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  g a combination 
35690 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b  of the.**      [
356a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
356b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
356c0 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73  EMSTATUS],...) s
356d0 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  tart-time option
356e0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65   and.**      the
356f0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
35700 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70  _MEMSTATUS] comp
35710 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
35720 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65  .** <li> An alte
35730 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63  rnative page cac
35740 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
35750 6e 20 69 73 20 73 70 65 63 69 66 69 65 64 20 75  n is specified u
35760 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71  sing.**      [sq
35770 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
35780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
35790 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c  CHE],...)..** <l
357a0 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 63 68  i> The page cach
357b0 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d  e allocates from
357c0 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20   its own memory 
357d0 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a  pool supplied.**
357e0 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
357f0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
35800 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
35810 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20  HE],...) rather 
35820 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f  than.**      fro
35830 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c  m the heap..** <
35840 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67  /ul>)^.**.** Beg
35850 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69  inning with SQLi
35860 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33  te version 3.7.3
35870 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
35880 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65  limit is enforce
35890 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  d.** regardless 
358a0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
358b0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  t the [SQLITE_EN
358c0 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
358d0 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69  GEMENT].** compi
358e0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
358f0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68  s invoked.  With
35900 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
35910 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
35920 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20  T],.** the soft 
35930 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e  heap limit is en
35940 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20  forced on every 
35950 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
35960 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b  n.  Without.** [
35970 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
35980 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
35990 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
359a0 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e  limit is only en
359b0 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d  forced.** when m
359c0 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
359d0 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63  ed by the page c
359e0 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73  ache.  Testing s
359f0 75 67 67 65 73 74 73 20 74 68 61 74 20 62 65 63  uggests that bec
35a00 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65  ause.** the page
35a10 20 63 61 63 68 65 20 69 73 20 74 68 65 20 70 72   cache is the pr
35a20 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79  edominate memory
35a30 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c   user in SQLite,
35a40 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
35a50 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65  tions will achie
35a60 76 65 20 61 64 65 71 75 61 74 65 20 73 6f 66 74  ve adequate soft
35a70 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f   heap limit enfo
35a80 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a  rcement without.
35a90 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53  ** the use of [S
35aa0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
35ab0 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e  ORY_MANAGEMENT].
35ac0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75  .**.** The circu
35ad0 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77  mstances under w
35ae0 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c  hich SQLite will
35af0 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66   enforce the sof
35b00 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79  t heap limit may
35b10 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66  .** changes in f
35b20 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
35b30 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
35b40 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
35b50 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 73 6f  int64 sqlite3_so
35b60 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
35b70 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e 29  sqlite3_int64 N)
35b80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35b90 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 53 6f  F: Deprecated So
35ba0 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20 49 6e  ft Heap Limit In
35bb0 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50 52 45  terface.** DEPRE
35bc0 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73  CATED.**.** This
35bd0 20 69 73 20 61 20 64 65 70 72 65 63 61 74 65 64   is a deprecated
35be0 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
35bf0 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
35c00 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
35c10 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 69   interface.  Thi
35c20 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72 6f  s routine is pro
35c30 76 69 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  vided for histor
35c40 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
35c50 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c  ty.** only.  All
35c60 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
35c70 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  s should use the
35c80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  .** [sqlite3_sof
35c90 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
35ca0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61 74 68  ] interface rath
35cb0 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e 65  er than this one
35cc0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
35cd0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
35ce0 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  D void sqlite3_s
35cf0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
35d00 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt N);.../*.** C
35d10 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74  API3REF: Extract
35d20 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20   Metadata About 
35d30 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61  A Column Of A Ta
35d40 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ble.**.** ^This 
35d50 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35d60 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61  metadata about a
35d70 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e   specific column
35d80 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a   of a specific.*
35d90 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  * database table
35da0 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e   accessible usin
35db0 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  g the [database 
35dc0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
35dd0 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  le.** passed as 
35de0 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69  the first functi
35df0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
35e00 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69  ** ^The column i
35e10 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
35e20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72  the second, thir
35e30 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
35e40 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68  ameters to.** th
35e50 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68  is function. ^Th
35e60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
35e70 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65  er is either the
35e80 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
35e90 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22  abase.** (i.e. "
35ea0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f  main", "temp", o
35eb0 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61  r an attached da
35ec0 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69  tabase) containi
35ed0 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ng the specified
35ee0 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c  .** table or NUL
35ef0 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c  L. ^If it is NUL
35f00 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61  L, then all atta
35f10 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61  ched databases a
35f20 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66  re searched.** f
35f30 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69  or the table usi
35f40 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
35f50 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68  rithm used by th
35f60 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
35f70 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20  e to.** resolve 
35f80 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c  unqualified tabl
35f90 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a  e references..**
35fa0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
35fb0 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
35fc0 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
35fd0 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61  ction are the ta
35fe0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a  ble and column.*
35ff0 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65  * name of the de
36000 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65  sired column, re
36010 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74  spectively. Neit
36020 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72  her of these par
36030 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62  ameters.** may b
36040 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d  e NULL..**.** ^M
36050 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72  etadata is retur
36060 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74  ned by writing t
36070 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63  o the memory loc
36080 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73  ations passed as
36090 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20   the 5th.** and 
360a0 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d  subsequent param
360b0 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
360c0 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20  nction. ^Any of 
360d0 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20  these arguments 
360e0 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20  may be.** NULL, 
360f0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
36100 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
36110 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64  element of metad
36120 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ata is omitted..
36130 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75  **.** ^(<blockqu
36140 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
36150 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
36160 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72  r><th> Parameter
36170 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e   <th> Output<br>
36180 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72  Type <th>  Descr
36190 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  iption.**.** <tr
361a0 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63  ><td> 5th <td> c
361b0 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
361c0 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72  Data type.** <tr
361d0 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63  ><td> 6th <td> c
361e0 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
361f0 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20  Name of default 
36200 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
36210 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37  ce.** <tr><td> 7
36220 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
36230 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
36240 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f   column has a NO
36250 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
36260 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74  t.** <tr><td> 8t
36270 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
36280 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
36290 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f  column is part o
362a0 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45  f the PRIMARY KE
362b0 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74  Y.** <tr><td> 9t
362c0 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
362d0 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
362e0 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49  column is [AUTOI
362f0 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74  NCREMENT].** </t
36300 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
36310 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
36320 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  The memory point
36330 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61  ed to by the cha
36340 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20  racter pointers 
36350 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65  returned for the
36360 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20  .** declaration 
36370 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69  type and collati
36380 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76  on sequence is v
36390 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20  alid only until 
363a0 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c  the next.** call
363b0 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41   to any SQLite A
363c0 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  PI function..**.
363d0 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
363e0 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63  fied table is ac
363f0 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61  tually a view, a
36400 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
36410 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
36420 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
36430 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72  ied column is "r
36440 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20  owid", "oid" or 
36450 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e  "_rowid_" and an
36460 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49  .** [INTEGER PRI
36470 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e  MARY KEY] column
36480 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63   has been explic
36490 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74  itly declared, t
364a0 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
364b0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
364c0 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70   set for the exp
364d0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
364e0 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68   column. ^(If th
364f0 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
36500 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
36510 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
36520 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74  Y KEY] column, t
36530 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
36540 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
36550 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a   set as follows:
36560 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
36570 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22      data type: "
36580 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20  INTEGER".**     
36590 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
365a0 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20  ce: "BINARY".** 
365b0 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a      not null: 0.
365c0 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b  **     primary k
365d0 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74  ey: 1.**     aut
365e0 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a  o increment: 0.*
365f0 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a  * </pre>)^.**.**
36600 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e   ^(This function
36610 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72   may load one or
36620 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72   more schemas fr
36630 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  om database file
36640 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f  s. If an.** erro
36650 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
36660 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72  this process, or
36670 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65   if the requeste
36680 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  d table or colum
36690 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66  n.** cannot be f
366a0 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20  ound, an [error 
366b0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
366c0 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
366d0 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69  essage left.** i
366e0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
366f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20  connection] (to 
36700 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69  be retrieved usi
36710 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  ng sqlite3_errms
36720 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  g()).)^.**.** ^T
36730 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20  his API is only 
36740 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
36750 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
36760 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
36770 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
36780 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
36790 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
367a0 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
367b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
367c0 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
367d0 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
367e0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
367f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36800 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
36810 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
36820 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
36830 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
36840 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
36850 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
36860 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
36870 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
36880 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36890 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
368a0 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
368b0 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
368c0 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
368d0 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
368e0 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
368f0 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
36900 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
36910 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
36920 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
36930 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
36940 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
36950 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
36960 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
36970 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
36980 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
36990 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
369a0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
369b0 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
369c0 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
369d0 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
369e0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
369f0 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
36a00 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
36a10 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
36a20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
36a30 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a  n Extension.**.*
36a40 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
36a50 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74  e loads an SQLit
36a60 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72  e extension libr
36a70 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d  ary from the nam
36a80 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed file..**.** ^
36a90 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
36aa0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
36ab0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
36ac0 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51  to load an.** SQ
36ad0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
36ae0 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64  ibrary contained
36af0 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69   in the file zFi
36b00 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65  le..**.** ^The e
36b10 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50  ntry point is zP
36b20 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d  roc..** ^zProc m
36b30 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63  ay be 0, in whic
36b40 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
36b50 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
36b60 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74  nt.** defaults t
36b70 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
36b80 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e  sion_init"..** ^
36b90 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
36ba0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
36bb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
36bc0 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  * [SQLITE_OK] on
36bd0 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
36be0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
36bf0 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
36c00 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ong..** ^If an e
36c10 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20  rror occurs and 
36c20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20  pzErrMsg is not 
36c30 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  0, then the.** [
36c40 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
36c50 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
36c60 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70  ace shall attemp
36c70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a  t to.** fill *pz
36c80 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f  ErrMsg with erro
36c90 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73  r message text s
36ca0 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  tored in memory.
36cb0 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
36cc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
36cd0 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67  ()]. The calling
36ce0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f   function.** sho
36cf0 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65  uld free this me
36d00 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20  mory by calling 
36d10 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
36d20 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69  ..**.** ^Extensi
36d30 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20  on loading must 
36d40 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  be enabled using
36d50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  .** [sqlite3_ena
36d60 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
36d70 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63  on()] prior to c
36d80 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c  alling this API,
36d90 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
36da0 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
36db0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
36dc0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61  ee also the [loa
36dd0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51  d_extension() SQ
36de0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a  L function]..*/.
36df0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
36e00 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
36e10 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  nsion(.  sqlite3
36e20 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
36e30 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e  * Load the exten
36e40 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64  sion into this d
36e50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36e60 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
36e70 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a  ar *zFile,    /*
36e80 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61   Name of the sha
36e90 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  red library cont
36ea0 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e  aining extension
36eb0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
36ec0 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45   *zProc,    /* E
36ed0 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72  ntry point.  Der
36ee0 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20  ived from zFile 
36ef0 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a  if 0 */.  char *
36f00 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20  *pzErrMsg       
36f10 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73  /* Put error mes
36f20 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74  sage here if not
36f30 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   0 */.);../*.** 
36f40 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
36f50 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
36f60 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
36f70 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74  .** ^So as not t
36f80 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20  o open security 
36f90 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61  holes in older a
36fa0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
36fb0 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72   are.** unprepar
36fc0 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  ed to deal with 
36fd0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
36fe0 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e  g, and as a mean
36ff0 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a  s of disabling.*
37000 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  * extension load
37010 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61  ing while evalua
37020 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65  ting user-entere
37030 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f  d SQL, the follo
37040 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70  wing API.** is p
37050 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20  rovided to turn 
37060 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
37070 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d  d_extension()] m
37080 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20  echanism on and 
37090 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65  off..**.** ^Exte
370a0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73  nsion loading is
370b0 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e   off by default.
370c0 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36   See ticket #186
370d0 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20  3..** ^Call the 
370e0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
370f0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
37100 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f  routine with ono
37110 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e  ff==1.** to turn
37120 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
37130 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69  ng on and call i
37140 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20  t with onoff==0 
37150 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61  to turn.** it ba
37160 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f  ck off again..*/
37170 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
37180 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
37190 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71  oad_extension(sq
371a0 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f  lite3 *db, int o
371b0 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
371c0 50 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69  PI3REF: Automati
371d0 63 61 6c 6c 79 20 4c 6f 61 64 20 53 74 61 74 69  cally Load Stati
371e0 63 61 6c 6c 79 20 4c 69 6e 6b 65 64 20 45 78 74  cally Linked Ext
371f0 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  ensions.**.** ^T
37200 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
37210 75 73 65 73 20 74 68 65 20 78 45 6e 74 72 79 50  uses the xEntryP
37220 6f 69 6e 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  oint() function 
37230 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
37240 72 0a 2a 2a 20 65 61 63 68 20 6e 65 77 20 5b 64  r.** each new [d
37250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37260 6f 6e 5d 20 74 68 61 74 20 69 73 20 63 72 65 61  on] that is crea
37270 74 65 64 2e 20 20 54 68 65 20 69 64 65 61 20 68  ted.  The idea h
37280 65 72 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 78  ere is that.** x
37290 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 69 73 20  EntryPoint() is 
372a0 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  the entry point 
372b0 66 6f 72 20 61 20 73 74 61 74 69 63 61 6c 6c 79  for a statically
372c0 20 6c 69 6e 6b 65 64 20 53 51 4c 69 74 65 20 65   linked SQLite e
372d0 78 74 65 6e 73 69 6f 6e 0a 2a 2a 20 74 68 61 74  xtension.** that
372e0 20 69 73 20 74 6f 20 62 65 20 61 75 74 6f 6d 61   is to be automa
372f0 74 69 63 61 6c 6c 79 20 6c 6f 61 64 65 64 20 69  tically loaded i
37300 6e 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61  nto all new data
37310 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
37320 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 6e 20 74  ..**.** ^(Even t
37330 68 6f 75 67 68 20 74 68 65 20 66 75 6e 63 74 69  hough the functi
37340 6f 6e 20 70 72 6f 74 6f 74 79 70 65 20 73 68 6f  on prototype sho
37350 77 73 20 74 68 61 74 20 78 45 6e 74 72 79 50 6f  ws that xEntryPo
37360 69 6e 74 28 29 20 74 61 6b 65 73 0a 2a 2a 20 6e  int() takes.** n
37370 6f 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20  o arguments and 
37380 72 65 74 75 72 6e 73 20 76 6f 69 64 2c 20 53 51  returns void, SQ
37390 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 78 45 6e  Lite invokes xEn
373a0 74 72 79 50 6f 69 6e 74 28 29 20 77 69 74 68 20  tryPoint() with 
373b0 74 68 72 65 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  three.** argumen
373c0 74 73 20 61 6e 64 20 65 78 70 65 63 74 73 20 61  ts and expects a
373d0 6e 64 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  nd integer resul
373e0 74 20 61 73 20 69 66 20 74 68 65 20 73 69 67 6e  t as if the sign
373f0 61 74 75 72 65 20 6f 66 20 74 68 65 0a 2a 2a 20  ature of the.** 
37400 65 6e 74 72 79 20 70 6f 69 6e 74 20 77 68 65 72  entry point wher
37410 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  e as follows:.**
37420 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
37430 3c 70 72 65 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20  <pre>.** &nbsp; 
37440 20 69 6e 74 20 78 45 6e 74 72 79 50 6f 69 6e 74   int xEntryPoint
37450 28 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 73  (.** &nbsp;    s
37460 71 6c 69 74 65 33 20 2a 64 62 2c 0a 2a 2a 20 26  qlite3 *db,.** &
37470 6e 62 73 70 3b 20 20 20 20 63 6f 6e 73 74 20 63  nbsp;    const c
37480 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 2c 0a  har **pzErrMsg,.
37490 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e  ** &nbsp;    con
374a0 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
374b0 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 2a  3_api_routines *
374c0 70 54 68 75 6e 6b 0a 2a 2a 20 26 6e 62 73 70 3b  pThunk.** &nbsp;
374d0 20 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f    );.** </pre></
374e0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
374f0 0a 2a 2a 20 49 66 20 74 68 65 20 78 45 6e 74 72  .** If the xEntr
37500 79 50 6f 69 6e 74 20 72 6f 75 74 69 6e 65 20 65  yPoint routine e
37510 6e 63 6f 75 6e 74 65 72 73 20 61 6e 20 65 72 72  ncounters an err
37520 6f 72 2c 20 69 74 20 73 68 6f 75 6c 64 20 6d 61  or, it should ma
37530 6b 65 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20  ke *pzErrMsg.** 
37540 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 70 70 72  point to an appr
37550 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65  opriate error me
37560 73 73 61 67 65 20 28 6f 62 74 61 69 6e 65 64 20  ssage (obtained 
37570 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
37580 72 69 6e 74 66 28 29 5d 29 0a 2a 2a 20 61 6e 64  rintf()]).** and
37590 20 72 65 74 75 72 6e 20 61 6e 20 61 70 70 72 6f   return an appro
375a0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
375b0 64 65 5d 2e 20 20 5e 53 51 4c 69 74 65 20 65 6e  de].  ^SQLite en
375c0 73 75 72 65 73 20 74 68 61 74 20 2a 70 7a 45 72  sures that *pzEr
375d0 72 4d 73 67 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20  rMsg.** is NULL 
375e0 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 74  before calling t
375f0 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  he xEntryPoint()
37600 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
37610 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74  invoke.** [sqlit
37620 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 2a 70  e3_free()] on *p
37630 7a 45 72 72 4d 73 67 20 61 66 74 65 72 20 78 45  zErrMsg after xE
37640 6e 74 72 79 50 6f 69 6e 74 28 29 20 72 65 74 75  ntryPoint() retu
37650 72 6e 73 2e 20 20 5e 49 66 20 61 6e 79 0a 2a 2a  rns.  ^If any.**
37660 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 72   xEntryPoint() r
37670 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2c  eturns an error,
37680 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
37690 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
376a0 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f 72  open16()],.** or
376b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
376c0 32 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 70  2()] call that p
376d0 72 6f 76 6f 6b 65 64 20 74 68 65 20 78 45 6e 74  rovoked the xEnt
376e0 72 79 50 6f 69 6e 74 28 29 20 77 69 6c 6c 20 66  ryPoint() will f
376f0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ail..**.** ^Call
37700 69 6e 67 20 73 71 6c 69 74 65 33 5f 61 75 74 6f  ing sqlite3_auto
37710 5f 65 78 74 65 6e 73 69 6f 6e 28 58 29 20 77 69  _extension(X) wi
37720 74 68 20 61 6e 20 65 6e 74 72 79 20 70 6f 69 6e  th an entry poin
37730 74 20 58 20 74 68 61 74 20 69 73 20 61 6c 72 65  t X that is alre
37740 61 64 79 0a 2a 2a 20 6f 6e 20 74 68 65 20 6c 69  ady.** on the li
37750 73 74 20 6f 66 20 61 75 74 6f 6d 61 74 69 63 20  st of automatic 
37760 65 78 74 65 6e 73 69 6f 6e 73 20 69 73 20 61 20  extensions is a 
37770 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 20  harmless no-op. 
37780 5e 4e 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a  ^No entry point.
37790 2a 2a 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  ** will be calle
377a0 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
377b0 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61   for each databa
377c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
377d0 61 74 20 69 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  at is opened..**
377e0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
377f0 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74  qlite3_reset_aut
37800 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a  o_extension()]..
37810 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
37820 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65  t sqlite3_auto_e
37830 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a  xtension(void (*
37840 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69  xEntryPoint)(voi
37850 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d));../*.** CAPI
37860 33 52 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f  3REF: Reset Auto
37870 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20  matic Extension 
37880 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54  Loading.**.** ^T
37890 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 64 69  his interface di
378a0 73 61 62 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d  sables all autom
378b0 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20  atic extensions 
378c0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65  previously.** re
378d0 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b  gistered using [
378e0 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
378f0 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 53 51  ension()]..*/.SQ
37900 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
37910 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f  lite3_reset_auto
37920 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29  _extension(void)
37930 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  ;../*.** The int
37940 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
37950 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
37960 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74  anism is current
37970 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
37980 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
37990 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
379a0 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
379b0 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
379c0 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
379d0 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
379e0 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
379f0 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
37a00 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
37a10 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
37a20 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
37a30 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73  anism stabilizes
37a40 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
37a50 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
37a60 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
37a70 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
37a80 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
37a90 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
37aa0 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73  /*.** Structures
37ab0 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72   used by the vir
37ac0 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72  tual table inter
37ad0 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20  face.*/.typedef 
37ae0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
37af0 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62  tab sqlite3_vtab
37b00 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
37b10 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
37b20 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  nfo sqlite3_inde
37b30 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20  x_info;.typedef 
37b40 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
37b50 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74  tab_cursor sqlit
37b60 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a  e3_vtab_cursor;.
37b70 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
37b80 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71  qlite3_module sq
37b90 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f  lite3_module;../
37ba0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
37bb0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a  irtual Table Obj
37bc0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
37bd0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
37be0 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  {virtual table m
37bf0 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  odule}.**.** Thi
37c00 73 20 73 74 72 75 63 74 75 72 65 2c 20 73 6f 6d  s structure, som
37c10 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 61 20  etimes called a 
37c20 22 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  "virtual table m
37c30 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69  odule", .** defi
37c40 6e 65 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nes the implemen
37c50 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72  tation of a [vir
37c60 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a  tual tables].  .
37c70 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72  ** This structur
37c80 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c  e consists mostl
37c90 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72  y of methods for
37ca0 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a   the module..**.
37cb0 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c 20 74 61  ** ^A virtual ta
37cc0 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20 63 72  ble module is cr
37cd0 65 61 74 65 64 20 62 79 20 66 69 6c 6c 69 6e 67  eated by filling
37ce0 20 69 6e 20 61 20 70 65 72 73 69 73 74 65 6e 74   in a persistent
37cf0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
37d00 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 61  this structure a
37d10 6e 64 20 70 61 73 73 69 6e 67 20 61 20 70 6f 69  nd passing a poi
37d20 6e 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 73  nter to that ins
37d30 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c  tance.** to [sql
37d40 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
37d50 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  le()] or [sqlite
37d60 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
37d70 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72  v2()]..** ^The r
37d80 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65 6d 61  egistration rema
37d90 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  ins valid until 
37da0 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 20 62  it is replaced b
37db0 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a  y a different.**
37dc0 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c   module or until
37dd0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
37de0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65  onnection] close
37df0 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a  s.  The content.
37e00 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ** of this struc
37e10 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 63 68  ture must not ch
37e20 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20 69 73  ange while it is
37e30 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
37e40 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 73 65  .** any database
37e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a   connection..*/.
37e60 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
37e70 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56  odule {.  int iV
37e80 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
37e90 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33  xCreate)(sqlite3
37ea0 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
37eb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
37ec0 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
37ed0 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
37ee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
37ef0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
37f00 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
37f10 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29   int (*xConnect)
37f20 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
37f30 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
37f40 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
37f50 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
37f60 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
37f70 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
37f80 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
37f90 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
37fa0 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74  BestIndex)(sqlit
37fb0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
37fc0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
37fd0 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  fo*);.  int (*xD
37fe0 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  isconnect)(sqlit
37ff0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
38000 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f  .  int (*xDestro
38010 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  y)(sqlite3_vtab 
38020 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
38030 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
38040 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
38050 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
38060 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20   **ppCursor);.  
38070 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
38080 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
38090 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  r*);.  int (*xFi
380a0 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74  lter)(sqlite3_vt
380b0 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20  ab_cursor*, int 
380c0 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68  idxNum, const ch
380d0 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20  ar *idxStr,.    
380e0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
380f0 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61  argc, sqlite3_va
38100 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69  lue **argv);.  i
38110 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69  nt (*xNext)(sqli
38120 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
38130 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29  );.  int (*xEof)
38140 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
38150 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
38160 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33  xColumn)(sqlite3
38170 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
38180 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
38190 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
381a0 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76  Rowid)(sqlite3_v
381b0 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
381c0 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77  ite3_int64 *pRow
381d0 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70  id);.  int (*xUp
381e0 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74  date)(sqlite3_vt
381f0 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  ab *, int, sqlit
38200 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c  e3_value **, sql
38210 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20  ite3_int64 *);. 
38220 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73   int (*xBegin)(s
38230 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
38240 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ab);.  int (*xSy
38250 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  nc)(sqlite3_vtab
38260 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
38270 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74  (*xCommit)(sqlit
38280 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
38290 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61  .  int (*xRollba
382a0 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ck)(sqlite3_vtab
382b0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
382c0 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29  (*xFindFunction)
382d0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
382e0 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20  Vtab, int nArg, 
382f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
38300 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  e,.             
38310 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28            void (
38320 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65  **pxFunc)(sqlite
38330 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
38340 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
38350 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
38360 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70          void **p
38370 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
38380 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  Rename)(sqlite3_
38390 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e  vtab *pVtab, con
383a0 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a  st char *zNew);.
383b0 20 20 2f 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    /* The methods
383c0 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
383d0 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
383e0 71 6c 69 74 65 5f 6d 6f 64 75 6c 65 20 6f 62 6a  qlite_module obj
383f0 65 63 74 2e 20 54 68 6f 73 65 20 0a 20 20 2a 2a  ect. Those .  **
38400 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
38410 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 67 72 65  ersion 2 and gre
38420 61 74 65 72 2e 20 2a 2f 0a 20 20 69 6e 74 20 28  ater. */.  int (
38430 2a 78 53 61 76 65 70 6f 69 6e 74 29 28 73 71 6c  *xSavepoint)(sql
38440 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
38450 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
38460 78 52 65 6c 65 61 73 65 29 28 73 71 6c 69 74 65  xRelease)(sqlite
38470 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 69  3_vtab *pVTab, i
38480 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  nt);.  int (*xRo
38490 6c 6c 62 61 63 6b 54 6f 29 28 73 71 6c 69 74 65  llbackTo)(sqlite
384a0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 69  3_vtab *pVTab, i
384b0 6e 74 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt);.};../*.** C
384c0 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
384d0 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20   Table Indexing 
384e0 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b  Information.** K
384f0 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
38500 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a  _index_info.**.*
38510 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
38520 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75  dex_info structu
38530 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74  re and its subst
38540 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64  ructures is used
38550 20 61 73 20 70 61 72 74 0a 2a 2a 20 6f 66 20 74   as part.** of t
38560 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  he [virtual tabl
38570 65 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  e] interface to.
38580 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74  ** pass informat
38590 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63  ion into and rec
385a0 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66  eive the reply f
385b0 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 74 49 6e  rom the [xBestIn
385c0 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  dex].** method o
385d0 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  f a [virtual tab
385e0 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65  le module].  The
385f0 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a   fields under **
38600 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65  Inputs** are the
38610 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42  .** inputs to xB
38620 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65  estIndex and are
38630 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65   read-only.  xBe
38640 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20  stIndex inserts 
38650 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  its.** results i
38660 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74  nto the **Output
38670 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a  s** fields..**.*
38680 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73 74 72 61  * ^(The aConstra
38690 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f  int[] array reco
386a0 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73 65  rds WHERE clause
386b0 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20   constraints of 
386c0 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20  the form:.**.** 
386d0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 63 6f 6c 75  <blockquote>colu
386e0 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 62 6c 6f 63  mn OP expr</bloc
386f0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68  kquote>.**.** wh
38700 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74  ere OP is =, &lt
38710 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20  ;, &lt;=, &gt;, 
38720 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 28 54  or &gt;=.)^  ^(T
38730 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70  he particular op
38740 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f  erator is.** sto
38750 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69  red in aConstrai
38760 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e 67 20 6f 6e  nt[].op using on
38770 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  e of the.** [SQL
38780 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
38790 41 49 4e 54 5f 45 51 20 7c 20 53 51 4c 49 54 45  AINT_EQ | SQLITE
387a0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTR